Wiki source code of Swagger UI

Last modified by Erik Bakker on 2024/08/23 11:34

Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 In this microlearning, we will focus on the Swagger UI. We will explore how Swagger UI can be a crucial tool for testing and sharing your API Gateway. Swagger UI not only allows you to view and interact with your API’s specifications, but also provides essential details such as authorization, HTTP resource paths, operations, schemas, and example messages.
3
4 If you have any questions along the way, feel free to reach out to us at [[academy@emagiz.com>>mailto:academy@emagiz.com]].
5
6 == 1. Prerequisites ==
7
8 * Basic knowledge of the eMagiz platform
9
10 == 2. Key concepts ==
11
12 This microlearning centers around the Swagger UI page.
13 * With Swagger UI, we mean a user interface that (external) parties can access via the browser to see the specifications of your API Gateway and test their solutions simultaneously.
14 * With API Gateway, we mean a collection of RESTful API operations that can be published to the outside world to give them access to applications linked to your business process.
15
16 == 3. Swagger UI ==
17
18 The Swagger UI is a user interface that external parties can access via the browser to see the specifications of your API Gateway and test their solutions simultaneously. The Swagger UI comes with:
19
20 * Authorization
21 * HTTP Resource Paths
22 * HTTP Operations
23 * Schema's (if defined)
24 * Example messages (if defined)
25
26 Based on your initial configuration in the Design phase, eMagiz will generate the Swagger UI for you. When developing, eMagiz will utilize your gateway definitions to create schemas and example messages. Furthermore, it will use the configured paths and operations from the catalog to define them in the Swagger UI and link the schemas and example messages to each operation. On top of that, it will look at the configured authorization and explain it in the Swagger UI overview.
27
28 {{info}}Note that when opening the Swagger UI page, the default selected "server" for each eMagiz model is the one assigned to the Testlane of your model. If you want to change this, you can do so via Design -> Settings -> API Management -> Edit Settings. Once selected, eMagiz will update the Swagger UI file for you.{{/info}}
29
30 === 3.1 Updating Swagger UI ===
31
32 After the initial configuration is done in Design, many scenarios trigger an update of the Swagger UI file generated by eMagiz. The main scenarios are listed below. In this [[microlearning>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.API Management.intermediate-api-management-updating-your-api-gateway-operations||target="blank"]], we dive into this topic in more detail.
33
34 * Add a new integration to Create
35 * Update a definition in Create
36 ** Change datatype
37 ** Change/Add/Delete enumeration values
38 * Update an integration in Design
39 * Change path
40 * Change gateway message
41 * Change HTTP operation
42 * Change parameters
43
44 === 3.2 Access Swagger UI ===
45
46 You can access the Swagger UI when your solution is running (on the cloud or on your local device).
47 If you run the gateway in the eMagiz Cloud, for all environments, you can access the Swagger UI page in two ways. The first option is to press the Swagger UI button in Releases (when selecting the API Pattern).
48
49 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--button-releases.png]]
50
51 The other is via User Management in Deploy. Here, you can select a user to get to the Swagger UI Path, which can be copied and pasted into a new tab in your browser.
52
53 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--button-runtime-dashboard.png]]
54
55 ==== 3.2.1 Access Swagger UI on your local device ====
56
57 In case you want to run your API Gateway solution on your local device for testing purposes, you can access the Swagger UI by opening a new browser tab and entering the following URL:
58
59 * {{code}}http://localhost:{gateway.entry.port}/swaggerui/index.html{{/code}}
60
61 You must replace the {gateway.entry.port} with the default port that eMagiz defines. This will always be port 9091. So the URL would be:
62
63 * {{code}}http://localhost:9092/swaggerui/index.html{{/code}}
64
65 {{warning}}Note that you need a running docker (desktop) installation to run eMagiz runtimes on your local device.{{/warning}}
66
67 === 3.3 Reading Swagger UI ===
68
69 After you have accessed Swagger UI, you will see all endpoints available for your API Gateway implementation.
70
71 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-overview.png]]
72
73 As you can see from the overview, you first encounter the Authorize button.
74 By clicking on that, you will see a pop-up where you need to fill in the authorization details—in this case, a valid API Key.
75
76 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-authorization.png]]
77
78 Below, you see all operations grouped per tag (if applicable). If the operations don't have a tag, they are alphabetically sorted. In this simple example, we only have one operation on one integration, as you can see.
79
80 By clicking on an operation, you can see the detailed information of that operation. Here, you can see the Example Value and Schema. You can see what is mandatory in the Schema, indicated by the red asterisk icon in front of the attribute or element.
81
82 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-example-value.png]]
83
84 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-schema.png]]
85
86 === 3.3 Testing with Swagger UI ===
87
88 Furthermore, there is a "try-it-out" button. After you press this button, a button called Execute will appear.
89 By pressing this button, you will test the API Gateway functionality.
90
91 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-execute-try-it-out.png]]
92
93 The Swagger UI will give feedback based on what happened after you have pressed the button to execute
94
95 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--feedback-inswagger-ui.png]]
96
97 == 4. Key takeaways ==
98
99 * Swagger UI provides a comprehensive view of your API Gateway, including details on:
100 ** Authorization
101 ** HTTP Resource Paths
102 ** HTTP Operations
103 ** Schema's (if defined)
104 ** Example messages (if defined)
105 * Swagger UI gives the external party an option to test the various operations.
106 * You can access Swagger UI via the eMagiz Cloud or locally on your device, making it versatile for both development and testing environments.
107
108 == 5. Suggested Additional Readings ==
109
110 If you are interested in this topic and want more information, please read the help text provided by eMagiz and the following link.
111
112 * [[Crash Course (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.WebHome||target="blank"]]
113 ** [[Crash Course API Gateway (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.WebHome||target="blank"]]
114 *** [[HTTP Resources (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-resource-paths||target="blank"]]
115 *** [[HTTP Operations (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-http-operations||target="blank"]]
116 *** [[Parameters (Path, Query) (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-parameters||target="blank"]]
117 *** [[Configure Roles and Users (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-configure-roles-and-users||target="blank"]]
118 *** [[API Gateway Security (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.crashcourse-api-gateway-security||target="blank"]]
119 * [[Intermediate Level (Menu)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.WebHome||target="blank"]]
120 ** [[Testing API Gateway (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Testing API Gateway.WebHome||target="blank"]]
121 *** [[Testing API Gateway (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Testing API Gateway.intermediate-testing-emagiz-api-gateway-testing-api-gateway||target="blank"]]
122 ** [[API Management (Navigation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.API Management.WebHome||target="blank"]]
123 *** [[Updating your API Gateway Operations (Explanation)>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.API Management.intermediate-api-management-updating-your-api-gateway-operations||target="blank"]]
124 * [[What is Swagger (External)>>https://swagger.io/docs/specification/2-0/what-is-swagger/||target="blank"]]
125 * [[Swagger UI (Search Results)>>url:https://docs.emagiz.com/bin/view/Main/Search?sort=score&sortOrder=desc&highlight=true&facet=true&r=1&f_space_facet=0%2FMain.&l_space_facet=10&f_type=DOCUMENT&f_locale=en&f_locale=&f_locale=en&text="Swagger%20UI"||target="blank"]]
126
127 )))((({{toc/}}))){{/container}}{{/container}}