Skip to Content
Last modified by Erik Bakker on 2026/01/02 14:41
From version 36.1
edited by Erik Bakker
on 2026/01/02 14:39
Change comment: There is no comment for this version
To version 35.60
edited by dfirdausy
on 2024/09/27 16:43
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.ebakker
1 +XWiki.dfirdausy
Content
... ... @@ -47,13 +47,11 @@
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 +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.
51 51  
52 -{{info}}As with all new flow versions in Create, changes will take effect only after deploying via Deploy phase, and to show the changes in the Swagger file to the end-user, the latest version of the API Gateway infra flow must be included and deployed.{{/info}}
53 -
54 54  ==== 3.3.1 Edit Resource ====
55 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).
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 two screenshots below of the Swagger UI).
57 57  
58 58  [[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-resource.png]]
59 59  
... ... @@ -63,48 +63,32 @@
63 63  
64 64  [[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-operation.png]]
65 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).
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" as the tag for {{code language='xml'}}/debtor/{code}{{/code}} and {{code}}/invoice{{/code}} operations (see the orange box below) along with the summaries of each of the resource paths (see the red box below).
67 67  
68 68  [[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--tags-summary.png]]
69 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).
68 +==== 3.3.2 Edit Parameters ====
71 71  
72 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--gateway-message-tags.png]]
70 +Still in the API Catalog page, right next to that "Operations" of that resource, you will see "Parameters", "Request", and "Responses" tabs. In the "Parameters" tab, you can specify the parameter's name (see the yellow box below), description (see the orange box below), the location of the parameter (see the blue box below), as well as whether the parameter is required or not (see the green box below).
73 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 82  [[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--parameters-description.png]]
83 83  
84 -==== 3.3.4 Edit Request ====
74 +==== 3.3.3 Edit Request ====
85 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). Do note that this tab is only visible for non-GET operation.
76 +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. The screenshot below shows how the Request "Description" is reflected in the Swagger UI.
87 87  
88 -[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--edit-request.png]]
78 +[[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--responses-description.png]]
89 89  
90 -The screenshot below shows how the request's description, schema, and example value are reflected in the Swagger UI.
80 +==== 3.3.4 Edit Responses ====
91 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}}
82 +Lastly, 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. The screenshot below shows what are listed in the "Responses" tab is reflected in the Swagger UI.
93 93  
94 94  [[image:Main.Images.Microlearning.WebHome@intermediate-api-management-updating-your-api-gateway-operations--request-description.png]]
95 95  
96 -==== 3.3.5 Edit Responses ====
86 +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.
97 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).
88 +{{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}}
99 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  
110 110  * Updates to your API Gateway can be made either during the Design phase or the Create phase, each with distinct impacts.
intermediate-api-management-updating-your-api-gateway-operations--reset-flow-warning.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.ebakker
Size
... ... @@ -1,0 +1,1 @@
1 +27.9 KB
Content