Swagger UI

Prerequisites

• An active Azure subscription, an SSH public key, and a VNet with a subnet in the target region
• A network security group that allows inbound TCP 22 (SSH), 80 (HTTP redirect) and 443 (HTTPS)

Security note: the Basic Auth credential protects the interface, but as defense in depth you should still restrict the inbound rule for ports 80 and 443 to trusted source ranges in your network security group. Alternatively, place the VM behind a reverse proxy or VPN.

Deploy from the Azure Marketplace

In the Azure portal, choose Create a resource and search for Swagger UI on Ubuntu 24.04 LTS by SecureAnyCloud.

Select the plan and click Create.

On the Basics tab, pick your subscription, resource group and region, give the VM a name, and choose a size. Standard_B2s is a good starting point for evaluation and light use. Scale up for heavier concurrent use.

Set the authentication type to SSH public key and provide your key. Set the inbound ports to allow SSH (22), HTTP (80) and HTTPS (443).

Select Review + create, then Create. When the deployment finishes, note the VM's public IP address.

On the first boot, swagger-ui-firstboot.service generates a per-VM self-signed TLS certificate, mints a per-VM Basic Auth password and starts nginx. It then confirms that the docs answer 401 without credentials and 200 with them, and writes the credential to a root-only file. This usually completes within a minute of the VM reaching the running state.

Retrieve the per-VM credential

SSH into the VM as azureuser and read the access note. It contains the URL, the admin username and the password generated uniquely for this VM on the first boot.

sudo cat /root/swagger-ui-credentials.txt

The note records the URL, the credential and how to change it. The password is unique to your instance and never leaves the VM.

Open the API documentation

Browse to https://<VM-public-IP>/. The image ships a self-signed certificate, so your browser warns you on the first visit. Accept the exception, or install your own certificate (see below).

The browser then prompts for the Basic Auth credential. Enter admin and the password from the access note. Swagger UI loads and renders the shipped Swagger Petstore definition.

• Click any operation to expand it and see its parameters, request body and responses, including an example value generated from the schema.
• Use Try it out to turn the documentation into an interactive request form, with editable parameters and an Execute button.
• Reusable schemas defined under components render in the Schemas section, with each property, type and constraint shown.

Verify the deployment

SSH into the VM as azureuser and confirm that nginx is active. nginx is the only network-facing process. It serves the static bundle over TLS on :443 behind Basic Auth and redirects :80 to HTTPS.

sudo systemctl start nginx.service systemctl is-active nginx.service swagger-ui-firstboot.service | paste -sd' ' - ss -tln | grep -E ':443 |:80 ' | awk '{print $1, $4}' test -f /var/lib/sac/data/swagger-ui-firstboot.done && echo 'firstboot sentinel present'

Once the first boot has completed, nginx reports active and listens on public ports 80 and 443:

active active LISTEN 0.0.0.0:443 LISTEN 0.0.0.0:80 LISTEN [::]:443 LISTEN [::]:80 firstboot sentinel present

Secure by default: HTTP Basic Auth

This appliance never opens the API docs to the world. The health probe is unauthenticated so that a load balancer can check it. The documentation itself returns 401 without credentials and 200 only with the per-VM admin password.

Prove the round trip directly on the VM. The commands read the password from the access note:

PW=$(sudo grep '^swagger.ui.password=' /root/swagger-ui-credentials.txt | cut -d= -f2-)
echo "GET / (no credentials) -> HTTP $(curl -sk -o /dev/null -w '%{http_code}' -m5 https://127.0.0.1/)"
echo "GET /healthz -> HTTP $(curl -sk -o /dev/null -w '%{http_code}' -m5 https://127.0.0.1/healthz)"
echo "GET / (with credentials) -> HTTP $(curl -sk -u "admin:$PW" -o /dev/null -w '%{http_code}' -m5 https://127.0.0.1/)"
echo "GET :80/ -> HTTP $(curl -s -o /dev/null -w '%{http_code}' -m5 http://127.0.0.1/)"

The health check returns 200 without credentials. The docs return 401 without them and 200 with them. Port 80 redirects with 301:

GET / (no credentials) -> HTTP 401 GET /healthz -> HTTP 200 GET / (with credentials) -> HTTP 200 GET :80/ -> HTTP 301

Runtime and versions

On the VM, you can inspect the runtime stack, the exact Swagger UI distribution version and checksum, and the unit enabled for your first boot:

nginx -v cat /var/www/swagger-ui/SAC_VERSION systemctl is-enabled nginx.service curl -s -o /dev/null -w 'GET /healthz -> HTTP %{http_code}\n' -m 5 http://127.0.0.1/healthz

The served root records the pinned distribution version and its sha256:

nginx version: nginx/1.24.0 (Ubuntu) swagger_ui_dist_version=5.32.11 swagger_ui_dist_sha256=966b7c7ea3bc98af2f5f125dac3a971973df20ed1f9c40707d846200d8b462a6 upstream=https://github.com/swagger-api/swagger-ui licence=Apache-2.0 enabled GET /healthz -> HTTP 200

Bring your own API definition

The image ships a self-contained Swagger Petstore demo definition at /var/www/swagger-ui/openapi.json so the docs render out of the box. To document your own service, replace that file with your own OpenAPI or Swagger definition. Swagger UI is configured to load openapi.json from the served root, so no other change is needed:

# The shipped demo definition lives here:
sudo ls -l /var/www/swagger-ui/openapi.json
# To document your own service, copy your definition over it, keeping the same path:
#
sudo cp my-api.json /var/www/swagger-ui/openapi.json
# (optionally back up the demo first:
sudo cp /var/www/swagger-ui/openapi.json ~/openapi.json.demo)

To keep multiple definitions, drop them into the served root. Then change the url value in /var/www/swagger-ui/swagger-initializer.js to point at the one you want, or add a urls array for a definition picker. No service restart is needed, because nginx serves the files directly.

Change the Basic Auth password

The per-VM password is stored, apr1-hashed, in /etc/nginx/auth/swagger-ui.htpasswd (user admin). To set your own password, generate a new hash and reload nginx:

sudo sh -c 'openssl passwd -apr1 "your-new-password" | sed "s#^#admin:#" > /etc/nginx/auth/swagger-ui.htpasswd'
sudo nginx -t sudo systemctl reload nginx

To add more users, append further user:hash lines to the same file.

Offline and air-gapped use

The documentation runs entirely offline. The bundle, styles, scripts and the demo definition are all served from the VM, so it works with no internet access.

Some Swagger UI deployments call out to validator.swagger.io from the browser for the external spec validator badge. This image disables the badge (validatorUrl is set to null), so the browser makes no third-party calls. As shipped, the appliance is ready for fully offline or air-gapped networks.

Bring your own TLS certificate

The image serves HTTPS with a self-signed certificate that is regenerated per VM on the first boot. It is unique to your instance but not trusted by browsers. For production, replace it with a certificate for your own domain, then reload nginx.

Point a DNS record at the VM's public IP.

Copy your certificate chain to /etc/nginx/tls/swagger-ui.crt and your private key to /etc/nginx/tls/swagger-ui.key. Keep the key mode 0600.

Alternatively, place the VM behind an Azure Application Gateway or another reverse proxy that terminates TLS with a managed certificate.

After replacing the files, validate the configuration before you reload the web server:

sudo nginx -t

A successful nginx -t confirms that the configuration is valid. You can then reload nginx.

Support

SecureAnyCloud maintains this image with 24/7 support and a guaranteed 24-hour response SLA. Swagger UI is free, open-source software licensed under the Apache License 2.0. The SecureAnyCloud charge covers packaging, security patching, image maintenance and support. For help, contact sales@secureanycloud.com.

Deploy on Azure

Launch Swagger UI on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com