Hosting SDK5 API Documentation with Swagger UI (Docker)

It explains how to:

1. Locate and adjust the sdk5-openapi.yaml file

2. Build a custom Swagger UI Docker image that embeds this file

3. Run the container and access the SDK5 API documentation

Prerequisites

You will need:

• The source code package (containing the OpenAPI YAML file)

• The backend URL of your SDK5 server (for example: https://your-backend-domain.com/api)

• Docker installed on your machine or server

1. Locate the sdk5-openapi.yaml file

1. Open the Google Drive folder that contains the source code release for the required version.

2. Find the archive named: <release_version>_sdk5_openapi_generator.zip

3. Unzip this file. You will get the directory named: <release_version>_sdk5_openapi_generator

4. Inside this directory, navigate to: src/main/resources/schemas/sdk5-openapi.yaml

This sdk5-openapi.yaml file is the one you will use

2. Update the OpenAPI configuration

Open sdk5-openapi.yaml in any text editor. At the top of the file, you will see something like:

Make the following changes:

1. Remove unnecessary lines:

   • You can remove lines 16-25, as they are not needed for you deployment

2. Update the server URL

   • On line 14, replace the value of url with the URL of you backend server.

   • Make sure that {basePath} remains set to api.

   • Use https:// if your backend is available or HTTPS

For example:

These are the only changes you need to make in the sdk5-openapi.yaml file. After that, the file is ready to be used with Swagger UI.

For the Docker image we will rename it to library-api.yaml inside the container, but the content stays the same

3. Prepare the project structure for Docker

Create the small project directory, for example:

Place the updated sdk5-openapi.yaml into src/main/resources/schemas/ as shown above.

4. Create the Dockerfile (Swagger UI + SDK5 spec)

In project-root, create Dockerfile with the following content:

Explanation:

• The SDK5 OpenAPI file is copied into the container as /usr/share/nginx/html/library-api.yaml

• URLS configures Swagger UI to load this spec:

  • url: “library-api.yaml“ – path to the spec relative to the HTML root

  • name: “API“ – label that appears in the Swagger UI dropdown

• BASE_URL=’/’ ensures Swagger UI is served from the root path.

5. Build the Docker image

From project-root, run:

For example:

You can verify the image exists:

6. Run the docker container

Start the container:

Notes:

• The official swaggerapi/swagger-ui image listens on port 8080 inside the container

• -p 8080:8080 exposes it on http://localhost:8080 on the host\

Check that the container is running:

You should see sdk5-swagger-ui with a status like UP … and port mapping 0.0.0.0:8080->8080/tcp.

7. Access the SDK5 API documentation

Open a browser and go to:

You should see:

• The Swagger UI interface

• All endpoints defined in your adjusted sdk5-openapi.yaml (now served as library-api.yaml inside the container)

8. Troubleshooting (HTTP)

White screen / blank page

• Open browser DevTools → Console and look for JavaScript errors

• Common causes:

  • Invalid YAML in sdk5-openapi.yaml

  • Incorrect URLS value in the Dockerfile (typo or missing quotes)

Container starts and then exits

• Check the logs:

  docker logs sdk5-swagger-ui

• Any syntax errors or configuration issues will be printed there

9. Hosting Swagger UI over HTTPS with Nginx

In a production environment, you usually want to serve the documentation over HTTPS using a real name domain, such as

The recommended setup is:

• The Swagger UI container continues to server HTTP on port 8080

• Nginx is run on the same server (or in front of it) and:

  • terminated SSL (handles HTTPS)

  • proxies requests on the Swagger UI container

9.1 Requirements

• A Linux server (e.g. Ubuntu) with Nginx installed:

  sudo apt update
sudo apt install nginx

• A public DNS record pointing swagger.your-domain.com to your server’s IP

• An SSL certificate for swagger.your-domain.com:

  • either issued by a CA and stored as .crt + .key files

  • or obtained via Let’s Encrypt (e.g. using certbot)

9.2 Run the Swagger UI container for production

On the server where Nginx runs, start the Swagger UI container and expose it on localhost:8080:

Binding to 127.0.0.1 ensures the container is accessible only locally (Nginx will be the public entry point)

9.3 Nginx Configuration (with SSL)

Create a new Nginx server block, for example:

Option A – Standart HTTP->HTTPS setup (port 80 open)

If port 80 can be open (recommended and simplest for Let’s Encrypt HTTP-01):

Option B – Port 80 must remain closed (use DNS challenge)

If you are not allowed to open port 80, you can still obtain and renew certificates using a DNS-01 challenge with your DNS provider:

• Configure Let’s Encrypt / certbot (or another ACME client) to use a DNS challenge plugin for your DNS provider

• In that case, you can run only the HTTPS server block:

  server {
listen 443 ssl;
server_name docs.your-domain.com;
ssl_certificate /etc/letsencrypt/live/docs.your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/docs.your-domain.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
}

In this setup:

• Port 80 remains closed on the server/firewall

• Certificate issuance and renewal are handled via DNS-01 (TXT records in DNS), so HTTP access on port 80 is not required

After creating the config (either Option A or B), reload Nginx:

Your documentation should be available at: