Skip to Content
Last modified by Erik Bakker on 2026/01/02 14:41
From version 35.78
edited by dfirdausy
on 2024/09/30 12:39
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,60 +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.
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 -==== 3.3.1 Edit Resource ====
53 -
54 -To have these information explicitly mentioned in your Swagger UI, then you need to define them in your API Catalog in Design. 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 in the second screenshot of Section 3.3.2 below of the Swagger UI).
55 -
56 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-resource.png]]
57 -
58 -==== 3.3.2 Edit Operation ====
59 -
60 -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).
61 -
62 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-operation.png]]
63 -
64 -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).
65 -
66 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--tags-summary.png]]
67 -
68 -==== 3.3.3 Edit Parameters ====
69 -
70 -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.
71 -
72 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-parameters.png]]
73 -
74 -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).
75 -
76 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--parameters-description.png]]
77 -
78 -==== 3.3.4 Edit Request ====
79 -
80 -Quite similar with the "Parameters" tab, in the "Request" tab of the API Catalog page, you can also specify the description and whether the request body is required in the request. Note that this tab is only visible for non-GET operation.
81 -
82 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-request.png]]
83 -
84 -The screenshot below shows how the Request "Description" is reflected in the Swagger UI.
85 -
86 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--request-description.png]]
87 -
88 -==== 3.3.5 Edit Responses ====
89 -
90 -The "Responses" tab of the API Catalog page also allows you to specify the response description and example response (along with its "Media type") for a specific HTTP status code.
91 -
92 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-responses.png]]
93 -
94 -The screenshot below shows what are listed in the "Responses" tab is reflected in the Swagger UI.
95 -
96 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--responses-description.png]]
97 -
98 -Lastly, 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.
99 -
100 100  {{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}}
101 101  
102 102  == 4. Key takeaways ==
103 103  
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 +
104 104  * Updates to your API Gateway can be made either during the Design phase or the Create phase, each with distinct impacts.
105 105  * 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.
106 106  * 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.
... ... @@ -107,6 +107,7 @@
107 107  * Adding new operations or updating from either Design or Create does not require a reset of the existing solution.
108 108  * Ensure that updates are included in the deployment phase to reflect the latest changes in the Swagger file and runtime infra flow.
109 109  
69 +
110 110  == 5. Suggested Additional Readings ==
111 111  
112 112  If you are interested in this topic and want more information, please read the help text provided by eMagiz and see the following link: