Wiki source code of Swagger UI

Last modified by Eva Torken on 2023/06/08 11:48
Show last authors
1 {{container}}{{container layoutStyle="columns"}}(((
2 In this microlearning, we will focus on learning how you can use the Swagger UI.
3 To test your API Gateway and more importantly to let others test your API Gateway solution the Swagger UI can play a vital role. Among others it specifies:
4
5 * Authorization
6 * HTTP Resource Paths
7 * HTTP Operations
8 * Schema's
9 * Example messages
10
11 Should you have any questions, please contact [[academy@emagiz.com>>mailto:academy@emagiz.com]].
12
13 == 1. Prerequisites ==
14
15 * Basic knowledge of the eMagiz platform
16
17 == 2. Key concepts ==
18
19 This microlearning centers around Swagger UI for the API Gateway solution of eMagiz.
20 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 at the same time
21 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 that are linked to your business process
22
23 Having a Swagger UI is of great importance to let others test your API Gateway Solution. The Swagger UI comes with:
24
25 * Authorization
26 * HTTP Resource Paths
27 * HTTP Operations
28 * Schema's (if defined)
29 * Example messages (if defined)
30
31 == 3. Swagger UI ==
32
33 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 at the same time.
34 Based on your configuration in the Design phase, eMagiz will generate the Swagger UI for you. The only thing that you need to specify is the port of which the endpoints are hosted.
35 You can do that by configuring the following property:
36
37 * gateway.entry.port
38
39 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--port-property.png]]
40
41 === 3.1 Access Swagger UI ===
42
43 When your solution is running (cloud or on your local device) you can access the Swagger UI.
44 In case you are running 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).
45
46 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--button-releases.png]]
47
48 The other is via the Runtime Dashboard of the Gateway.
49
50 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--button-runtime-dashboard.png]]
51
52 Clicking on that button will automatically open a new tab on your browser that will guide you to the Swagger UI.
53
54 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:
55
56 * {{code}}http://localhost:{gateway.entry.port}/swaggerui/swaggerui{{/code}}
57
58 You need to replace the {gateway.entry.port} with the port that you have configured yourself. So when you choose port 9092 the URL would be:
59
60 * {{code}}http://localhost:9092/swaggerui/swaggerui{{/code}}
61
62 === 3.2 Reading Swagger UI ===
63
64 After you have accessed Swagger UI you will see all endpoints that are available for your API Gateway implementation.
65
66 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-overview.png]]
67
68 As you can see from the overview the first thing you encounter is the Authorize button.
69 By clicking on that you get a pop-up where you need to fill in the authorization details. In this case a valid API Key.
70
71 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-authorization.png]]
72
73 Below that, you see all operations grouped per integration. In this simple example case, we only have one operation on one integration as you can see.
74
75 By clicking on an operation you can see the detailed information of that operation. Here you can see the Example Value and Schema.
76 In the Schema, you can see what is mandatory indicated by the red asterisk icon in front of the attribute or element
77
78 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-example-value.png]]
79
80 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-schema.png]]
81
82 === 3.3 Testing with Swagger UI ===
83
84 Furthermore, there is a try-it-out button. After you have pressed this button you will see a button called Execute appear.
85 By pressing this button you will test the API Gateway functionality.
86
87 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-execute-try-it-out.png]]
88
89 The Swagger UI will give feedback based on what happened after you have pressed the button to execute
90
91 [[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--feedback-inswagger-ui.png]]
92
93 == 4. Key takeaways ==
94
95 * Swagger UI gives you information on
96 ** Authorization
97 ** HTTP Resource Paths
98 ** HTTP Operations
99 ** Schema's (if defined)
100 ** Example messages (if defined)
101 * Swagger UI gives the external party a option to test the various operations
102
103 == 5. Suggested Additional Readings ==
104
105 If you are interested in this topic and want more information on it please read the help text provided by eMagiz and read the following linked"
106
107 * https://swagger.io/docs/specification/2-0/what-is-swagger/
108
109 )))((({{toc/}}))){{/container}}{{/container}}