Swagger UI

Last modified by Eva Torken on 2023/06/08 11:48

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:

  • Authorization
  • HTTP Resource Paths
  • HTTP Operations
  • Schema's
  • Example messages

Should you have any questions, please contact academy@emagiz.com.

1. Prerequisites

  • Basic knowledge of the eMagiz platform

2. Key concepts

This microlearning centers around Swagger UI for the API Gateway solution of eMagiz.
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
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

Having a Swagger UI is of great importance to let others test your API Gateway Solution. The Swagger UI comes with:

  • Authorization
  • HTTP Resource Paths
  • HTTP Operations
  • Schema's (if defined)
  • 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.
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.
You can do that by configuring the following property:

  • gateway.entry.port

crashcourse-api-gateway-swagger-ui--port-property.png

3.1 Access Swagger UI

When your solution is running (cloud or on your local device) you can access the Swagger UI.
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).

crashcourse-api-gateway-swagger-ui--button-releases.png

The other is via the Runtime Dashboard of the Gateway.

crashcourse-api-gateway-swagger-ui--button-runtime-dashboard.png

Clicking on that button will automatically open a new tab on your browser that will guide you to the Swagger UI.

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:

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

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:

  • http://localhost:9092/swaggerui/swaggerui

3.2 Reading Swagger UI

After you have accessed Swagger UI you will see all endpoints that are available for your API Gateway implementation.

crashcourse-api-gateway-swagger-ui--swagger-ui-overview.png

As you can see from the overview the first thing you encounter is the Authorize button.
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.

crashcourse-api-gateway-swagger-ui--swagger-ui-authorization.png

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.

By clicking on an operation you can see the detailed information of that operation. Here you can see the Example Value and Schema.
In the Schema, you can see what is mandatory indicated by the red asterisk icon in front of the attribute or element

crashcourse-api-gateway-swagger-ui--swagger-ui-example-value.png

crashcourse-api-gateway-swagger-ui--swagger-ui-schema.png

3.3 Testing with Swagger UI

Furthermore, there is a try-it-out button. After you have pressed this button you will see a button called Execute appear.
By pressing this button you will test the API Gateway functionality.

crashcourse-api-gateway-swagger-ui--swagger-ui-execute-try-it-out.png

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

crashcourse-api-gateway-swagger-ui--feedback-inswagger-ui.png

4. Key takeaways

  • Swagger UI gives you information on
    • Authorization
    • HTTP Resource Paths
    • HTTP Operations
    • Schema's (if defined)
    • Example messages (if defined)
  • Swagger UI gives the external party a option to test the various operations

5. Suggested Additional Readings

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"

Tags:
eMagiz
1.0.0