accessing-swagger-ui.adoc

Accessing {productname} Swagger UI

{productname} administrators and users can interacting with the API by using the Swagger UI-an interactive web interface that compiles executable commands. The Swagger UI can be launched as a container that points to your {productname} instance’s API discovery endpoint (/api/v1/discovery). After deploying the container, you can access the Swagger UI, which loads the OpenAPI specification for {productname} from the specified URL. {productname} administrators and users can explore the available endpoints and their structure.

Use the following procedure to access the {productname} Swagger UI.

Procedure

1. Enter the following command to deploy the Swagger UI container, pointing the URL to your {productname}'s API discovery endpoint. For example:

   $ podman run -p 8080:8080 -e SWAGGER_JSON_URL=<quay-server.example.com> docker.swagger.io/swaggerapi/swagger-ui
   Example output

   ---
   /docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
   20-envsubst-on-templates.sh: Running envsubst on /etc/nginx/templates/default.conf.template to /etc/nginx/conf.d/default.conf
   /docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
   /docker-entrypoint.sh: Launching /docker-entrypoint.d/40-swagger-ui.sh
   /docker-entrypoint.sh: Configuration complete; ready for start up
   ---

2. Navigate to the localhost URL. In this example, it is http://localhost:8080/.

3. Use the Swagger UI to test various API endpoints. For example, to create a new token for a user, you can click the POST /api/v1/user/apptoken endpoint → Try it out → Execute to generate an example curl command.

   Note

   Currently, server responses cannot be generated. This is because the Swagger UI is not set up to accept bearer tokens. As a result, the following error is returned for each command: {"error": "CSRF token was invalid or missing."}. As a workaround, you can copy this command into your terminal and manually add your bearer token, for example, -H 'Authorization: Bearer <bearer_token>'