Adding Support for Swagger UI

Liberty supports interactive API exploration through Swagger UI, which allows you to test and verify your environment setup.

Each endpoint includes detailed description of its purpose and parameters, along with sample inputs to help you try out the API promptly.

This feature is enabled by default, and you can access it through the following two endpoints:
  • /explorer – Renders the Swagger UI and displays all supported API endpoints.
  • /docs – Returns the OpenAPI definition as a YAML document.
The complete URL for these endpoints are logged in the server's output stream during startup. Look for the following lines near the top of the output. If the endpoints are not logged, then ask your system programmer to update Debug Profile Service to the latest version.
[AUDIT ] CWWKT0016I: Web application available (default_host): <explorer endpoint>
[AUDIT ] CWWKT0016I: Web application available (default_host): <docs endpoint>
To invoke API endpoints using Swagger UI, you must first authenticate:
  1. Click the green Authorize button in the top-right corner.
  2. An Available authorization popup will appear with options for Basic or Bearer (JWT) authentication.
  3. Choose one of the following methods based on your environment:
    1. Basic – Enter your username and password directly.
    2. Bearer (JWT) – First, obtain a JWT token by calling the /login endpoint under the Authentication section:
      1. Click the arrow next to /login to expand it.
      2. Select Try it out and enter your username and password.
      3. Execute the request to retrieve a JWT token.
      4. Copy the token and paste it into the Bearer field in the Authorize popup.
  4. Click Authorize, and then Close to save your authentication settings.
To confirm that the authentication is successful, try to invoke the /query endpoint under the Authentication section:
  • If you have used Basic, Swagger UI will send credentials using the Authorization: Basic header.
  • If you have used Bearer, Swagger UI will send the token using the Authorization: Bearer header.

If the request succeeds, you can proceed to explore and test the other endpoints.

Note:
  • If you use AT-TLS, you must specifically configure Swagger UI to use HTTPS instead of HTTP. Liberty is not AT-TLS aware, so it defaults to HTTP when generating the server URL.
  • To override the default hostname or protocol used by Swagger UI, set the swaggerUIServers property. For configuration details, refer to the eqaprof.env file.