Skip to Content
Last modified by Erik Bakker on 2026/01/02 14:41
From version 35.99
edited by dfirdausy
on 2024/09/30 17:05
Change comment: There is no comment for this version
To version 35.7
edited by dfirdausy
on 2024/09/18 13:31
Change comment: There is no comment for this version

Summary

Details

Page properties
Content
... ... @@ -47,66 +47,19 @@
47 47  
48 48  === 3.3 Updating the Swagger UI ===
49 49  
50 -Additionally, you can also update the Swagger UI of your API Gateway solution, so that it better informs your (external) parties to see the specifications of your API Gateway. As you have learned from the [[previous microlearning>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-swagger-ui||target="blank"]], the Swagger UI contains information on, not only Authorization, HTTP Resource Paths, and HTTP Operations, but also schemas, example messages, tags, and descriptions if defined. You are able to configure almost all fields that you can see in the Swagger UI through the API Catalog in Design>Solution Design.
50 +As is the case with all new versions in Create, the changes will only be effective when you deploy your solution via the eMagiz Deploy phase.
51 51  
52 -{{info}}As is the case with all new versions in Create, the changes will only be effective when you deploy your solution via the eMagiz Deploy phase. To ensure that the changes below to your Swagger file generated by eMagiz are shown to the end-user, the latest version of the API Gateway runtime infra flow needs to be included in the release and deployed to the correct environment.{{/info}}
52 +{{info}}To ensure that the changes to your Swagger file generated by eMagiz are shown to the end-user, the latest version of the API Gateway runtime infra flow needs to be included in the release and deployed to the correct environment.{{/info}}
53 53  
54 -==== 3.3.1 Edit Resource ====
55 -
56 -As mentioned, to have these information explicitly mentioned in your Swagger UI, then you need to define them in your API Catalog. In this catalog page, you can find the resource that you want to work with. Given that your account has an edit permission in Design, then you can click "Edit" of that resource to edit its resource path, which will later be reflected in your Swagger UI (see the blue box below and in the second screenshot of Section 3.3.2 to see how it is reflected in the Swagger UI).
57 -
58 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-resource.png]]
59 -
60 -==== 3.3.2 Edit Operation ====
61 -
62 -Next to that, when you click one of your resources in the API Catalog page, then you can also edit the "Operations" attached to that resource (see the screenshot below).
63 -
64 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-operation.png]]
65 -
66 -In this "Edit Operation" pop-up page, you can specify the HTTP method of that operation. Next to that, you can also specify the "Tags" and the "Summary" of that operation. The "Summary" here shortly describes your resource path and will be shown beside the path of your resource. Whereas, the "Tags" here will group together the operations with the same tag names in your Swagger UI. Thus, the screenshot below shows an example of "Financials" (see the orange box below) as the tag for {{code language='xml'}}/debtor/{code}{{/code}} and {{code}}/invoice{{/code}} operations along with the summaries of each of the resource paths (see the red box below).
67 -
68 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--tags-summary.png]]
69 -
70 -Additionally, the value that you use as a "Tags" of an operation will also be reflected in the Gateway message definition page of that integration operation (see the screenshot below).
71 -
72 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--gateway-message-tags.png]]
73 -
74 -==== 3.3.3 Edit Parameters ====
75 -
76 -Still in the API Catalog page, right next to that "Operations" of that resource, you will see "Parameters", "Request" (only for non-GET operation), and "Responses" tabs.
77 -
78 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-parameters.png]]
79 -
80 -In this "Parameters" tab, you can specify the parameter's name (see the yellow box), description (see the orange box), the location of the parameter (see the blue box), as well as whether the parameter is required or not (see the green box).
81 -
82 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--parameters-description.png]]
83 -
84 -==== 3.3.4 Edit Request ====
85 -
86 -Quite similar with the "Parameters" tab, in the "Request" tab of the API Catalog page, you can also specify the description (see the orange box) and whether the request body is required in the request. Next to that, you can also specify yourself the schema and the example value for the request message (see the blue box). **Note** that this tab is only visible for non-GET operation.
87 -
88 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-request.png]]
89 -
90 -The screenshot below shows how the request's description, schema, and example value are reflected in the Swagger UI.
91 -
92 -{{info}}eMagiz will generate the schema and example value of the request message for you by default if you leave them empty.{{/info}}
93 -
94 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--request-description.png]]
95 -
96 -==== 3.3.5 Edit Responses ====
97 -
98 -Lastly, the "Responses" tab of the API Catalog page allows you to specify the response description (see the orange box) and example response for a specific HTTP status code. Similar to the "Request", when you edit the response for a certain HTTP status code, under the "Content" section, you can specify the expected "Media type", example message (see the blue box), as well as the schema of the response message (see the green box).
99 -
100 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-responses.png]]
101 -
102 -The screenshot below shows what are listed in the "Responses" tab is reflected in the Swagger UI. Note that in the example below we show the example message for the 400 HTTP status code.
103 -
104 -{{info}}eMagiz will generate the schema and example value of the response message for you by default if you leave them empty.{{/info}}
105 -
106 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--responses-description.png]]
107 -
108 108  == 4. Key takeaways ==
109 109  
56 +* Updating can happen from Design
57 +* Updating can happen from Create
58 +* Both situations have a different impact
59 +* Adding a new operation to an existing solution does not involve a reset
60 +* Updating from Create does not involve a reset
61 +* Updating from Design does not involve a reset
62 +
110 110  * Updates to your API Gateway can be made either during the Design phase or the Create phase, each with distinct impacts.
111 111  * Changes made in the Design phase affect the configuration of the entry gate and may necessitate updates to both entry and exit gates, depending on the nature of the changes.
112 112  * Changes during the Create phase typically involve modifications to gateway messages, with changes reflected automatically in the Swagger definition and a version bump of the infra flow.
... ... @@ -113,6 +113,7 @@
113 113  * Adding new operations or updating from either Design or Create does not require a reset of the existing solution.
114 114  * Ensure that updates are included in the deployment phase to reflect the latest changes in the Swagger file and runtime infra flow.
115 115  
69 +
116 116  == 5. Suggested Additional Readings ==
117 117  
118 118  If you are interested in this topic and want more information, please read the help text provided by eMagiz and see the following link: