Swagger Editor on Ubuntu 24.04 LTS on Azure User Guide

Overview

This guide covers the deployment and configuration of Swagger Editor on Ubuntu 24.04 LTS on Azure using cloudimg Azure Marketplace images. Swagger Editor is an open source, browser based editor for designing OpenAPI and Swagger API definitions. You write your specification in YAML or JSON in one pane and see the live rendered Swagger UI documentation, complete with request and response models, update beside it in real time, with inline validation catching schema errors as you type.

The image serves the official swagger-editor-dist v4.14.8 distribution, which is the prebuilt, ready to serve build of Swagger Editor and the exact content the official swaggerapi/swagger-editor container serves. cloudimg mirrors it natively behind nginx, which terminates HTTPS. Because Swagger Editor is a client side application, your API definitions live in your browser and on your own device rather than on the server, which makes self hosting a natural fit for teams that want a private, in house place to author API contracts. The distribution is pinned by exact version and verified against a checksum at build time.

Pure static web app. Swagger Editor has no backend, no database and no login. nginx serves only the static bundle plus an unauthenticated health endpoint, so the only network facing surface is the web server itself and the only per VM secret is the self signed TLS key generated on first boot.

What is included:

• Swagger Editor v4.14.8 (official swagger-editor-dist distribution), sha256 pinned

• nginx 1.24 serving the static bundle over TLS

• The upstream Apache 2.0 LICENSE and NOTICE vendored into the served root

• swagger-editor-firstboot.service systemd oneshot that generates a per VM TLS certificate, starts nginx, then proves the editor and a known asset are serving

• :80 redirects to HTTPS, plus an unauthenticated /healthz endpoint (nginx native, HTTP 200) for load balancer and probe checks

• No backend, no database, no login: nginx serves the static editor only, so there is no admin console and no default credential

• Ubuntu 24.04 LTS base with the latest security patches applied at build time

• Azure Linux Agent for seamless cloud integration and SSH key injection

• 24/7 cloudimg support with a guaranteed 24 hour response SLA

Prerequisites

• Active Azure subscription, an SSH public key, and a VNet plus subnet in the target region

• A network security group that allows inbound TCP 22 (SSH), 80 (HTTP redirect) and 443 (HTTPS)

• Important security note: Swagger Editor has no login and no access control of its own. Anyone who can reach the editor can use it. Restrict the inbound rule for ports 80 and 443 to trusted source ranges in your network security group, or place the VM behind an authenticating reverse proxy or VPN.

Deploy from the Azure Marketplace

1. In the Azure portal, choose Create a resource and search for Swagger Editor on Ubuntu 24.04 LTS by cloudimg.

2. Select the plan and click Create.

3. 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.

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

5. Review and create. When the deployment finishes, note the VM's public IP address.

On first boot, swagger-editor-firstboot.service generates a per VM self signed TLS certificate, starts nginx, then confirms the editor and a known asset are serving and writes a short access note. This usually completes within a minute of the VM reaching the running state.

Open the editor

Point a browser at https://<VM-public-IP>/. Because the image ships a self signed certificate, your browser will warn on first visit; accept the exception (or install your own certificate, see below). The full Swagger Editor loads, with the YAML or JSON editor on the left and the live rendered API documentation on the right.

Edit the definition on the left and the documentation updates as you type. Expand any operation to see its parameters, request body and responses, including an example value generated from your schema:

Reusable schemas defined under components render in the Schemas section, with each property, type and constraint shown:

Out of the box the editor opens with the classic Swagger Petstore OpenAPI 3.0 example, so you have a complete, valid definition to explore before authoring your own:

Your definitions are held client side, in your browser. Use File → Save as YAML (or JSON) to download the definition to your device, and File → Import file to load one back. Nothing is written to the server, so there is nothing to back up on the VM.

Verify the deployment

SSH into the VM as azureuser and confirm nginx is active. nginx is the only network facing process; it serves the static bundle over TLS on :443 and redirects :80 to HTTPS.

sudo systemctl start nginx.service
for i in $(seq 1 60); do
  code=$(curl -sk -o /dev/null -w '%{http_code}' -m 5 https://127.0.0.1/)
  [ "$code" = "200" ] && break
  sleep 2
done
systemctl is-active nginx.service

nginx reports active once first boot has completed.

Check the health endpoint, the editor page and a known editor asset over TLS. The health check needs no authentication and is ideal for a load balancer probe:

curl -sk -o /dev/null -w 'GET /healthz                  -> HTTP %{http_code}\n' https://127.0.0.1/healthz
curl -sk -o /dev/null -w 'GET / (editor)                -> HTTP %{http_code}\n' https://127.0.0.1/
curl -sk -o /dev/null -w 'GET /swagger-editor-bundle.js -> HTTP %{http_code}\n' https://127.0.0.1/swagger-editor-bundle.js

All three return HTTP 200. The listeners confirm that only nginx (80 and 443) is exposed:

ss -tln | grep -E ':80 |:443 '

A pure static app with no backend and no login

Swagger Editor is served as a set of static files. There is no application server, no database and no login, so there is no admin console to reach and no default credential. You can confirm it directly on the VM: nginx serves the bundle from /var/www/swagger-editor, :80 redirects to HTTPS, and the upstream Apache 2.0 licence is vendored into the served root.

sudo ls /var/www/swagger-editor
curl -sk -o /dev/null -w 'GET / (editor)   -> HTTP %{http_code}\n' https://127.0.0.1/
curl -s  -o /dev/null -w 'GET :80/ (301)   -> HTTP %{http_code}\n' http://127.0.0.1/
sudo grep -m1 'Apache License' /var/www/swagger-editor/LICENSE

Remember that Swagger Editor has no login of its own, so the editor is open to anyone who can reach it. Keep the inbound network security group rules tight.

Runtime and versions

The runtime stack, the exact Swagger Editor distribution version and checksum, and the units enabled for the customer's first boot can all be inspected on the VM:

nginx -v
cat /var/www/swagger-editor/CLOUDIMG_VERSION
systemctl is-enabled nginx.service swagger-editor-firstboot.service

The access note

On first boot the image writes a short, secret free access note to /root/swagger-editor-credentials.txt. Swagger Editor has no login, so no credential is generated or stored; the note simply records the editor URL and a reminder to restrict inbound access.

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

Offline and air-gapped use

The editor itself runs entirely offline: the bundle, styles and scripts are all served from the VM, so it works with no internet access. One optional feature does reach out from the browser: the spec validity badge asks the public validator.swagger.io service to validate your definition. This is a request made by your browser, not by the server. To turn it off for fully offline or air gapped use, add validatorUrl: null to the SwaggerEditorBundle({ ... }) options in /var/www/swagger-editor/index.html, or block outbound access from your clients to that host.

Bring your own TLS certificate

The image serves HTTPS with a self signed certificate that is regenerated per VM at first boot, so it is unique to your instance but not trusted by browsers. For production, replace it with a certificate for your own domain. Put your certificate and key in place and reload nginx:

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

• Copy your certificate chain to /etc/nginx/tls/swagger-editor.crt and your private key to /etc/nginx/tls/swagger-editor.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 the configuration is valid before you reload.

Support

This image is maintained by cloudimg with 24/7 support and a guaranteed 24 hour response SLA. Swagger Editor is free and open source software licensed under the Apache License 2.0; the cloudimg charge covers packaging, security patching, image maintenance and support. For help, contact support@cloudimg.co.uk.