Swagger UI - eMagiz

{{container}}{{container layoutStyle="columns"}}(((

In this microlearning, we will focus on learning how you can use the Swagger UI.

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

* HTTP Operations

* Schema's

* Example messages

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)

== 3. Swagger UI ==

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:

* gateway.entry.port

[[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

* http://localhost:{gateway.entry.port}/swaggerui/swaggerui

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

* http://localhost:9092/swaggerui/swaggerui

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

81

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-schema.png]]

82

83

=== 3.3 Testing with Swagger UI ===

84

85

Furthermore, there is a try-it-out button. After you have pressed this button you will see a button called Execute appear.

86

By pressing this button you will test the API Gateway functionality.

87

88

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-execute-try-it-out.png]]

89

90

The Swagger UI will give feedback based on what happened after you have pressed the button to execute

91

92

[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--feedback-inswagger-ui.png]]

== 4. Assignment ==

Run your API Gateway locally and access the Swagger UI via the browser. Authenticate yourself and test at least one operation.

97

This assignment can be completed with the help of the (Academy) project that you have created/used in the previous assignment.

98

99

== 5. Key takeaways ==

100

101

* Swagger UI gives you information on

102

* Authorization

103

* HTTP Resource Paths

104

* HTTP Operations

105

* Schema's (if defined)

106

* Example messages (if defined)

107

* Swagger UI gives the external party a option to test the various operations

108

109

== 6. Suggested Additional Readings ==

110

111

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"

112

113

* https://swagger.io/docs/specification/2-0/what-is-swagger/

114

115

== 7. Silent demonstration video ==

116

117

This video demonstrates how you could have handled the assignment and gives you some context on what you have just learned. Disclaimer, you only see the eMagiz part but if you follow the above steps you are good to go!

118

119

{{video attachment="crashcourse-api-gateway-swagger-ui.mp4" reference="Main.Videos.Microlearning.WebHome"/}}

120

121

)))((({{toc/}}))){{/container}}{{/container}}

version	line-number	content
51.1	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	* http://localhost:{gateway.entry.port}/swaggerui/swaggerui
	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	* http://localhost:9092/swaggerui/swaggerui
	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
	81	[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-schema.png]]
	82
	83	=== 3.3 Testing with Swagger UI ===
	84
	85	Furthermore, there is a try-it-out button. After you have pressed this button you will see a button called Execute appear.
	86	By pressing this button you will test the API Gateway functionality.
	87
	88	[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--swagger-ui-execute-try-it-out.png]]
	89
	90	The Swagger UI will give feedback based on what happened after you have pressed the button to execute
	91
	92	[[image:Main.Images.Microlearning.WebHome@crashcourse-api-gateway-swagger-ui--feedback-inswagger-ui.png]]
	93
	94	== 4. Assignment ==
	95
	96	Run your API Gateway locally and access the Swagger UI via the browser. Authenticate yourself and test at least one operation.
	97	This assignment can be completed with the help of the (Academy) project that you have created/used in the previous assignment.
	98
	99	== 5. Key takeaways ==
	100
	101	* Swagger UI gives you information on
	102	* Authorization
	103	* HTTP Resource Paths
	104	* HTTP Operations
	105	* Schema's (if defined)
	106	* Example messages (if defined)
	107	* Swagger UI gives the external party a option to test the various operations
	108
	109	== 6. Suggested Additional Readings ==
	110
	111	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"
	112
	113	* https://swagger.io/docs/specification/2-0/what-is-swagger/
	114
	115	== 7. Silent demonstration video ==
	116
	117	This video demonstrates how you could have handled the assignment and gives you some context on what you have just learned. Disclaimer, you only see the eMagiz part but if you follow the above steps you are good to go!
	118
	119	{{video attachment="crashcourse-api-gateway-swagger-ui.mp4" reference="Main.Videos.Microlearning.WebHome"/}}
	120
	121	)))((({{toc/}}))){{/container}}{{/container}}

Wiki source code of Swagger UI