--- title: "How to Host OpenAPI Docs with Swagger UI and ReDoc on Nginx" description: "Write and validate an OpenAPI spec, then publish it with Swagger UI and ReDoc behind Nginx and HTTPS on Ubuntu 24.04, with several API versions in one portal." category: "API and Microservices" language: en source: https://cubepath.com/docs/api-and-microservices/swagger-openapi-documentation-server updated: 2026-09-25 --- # How to Host OpenAPI Docs with Swagger UI and ReDoc on Nginx An OpenAPI document describes a REST API in YAML or JSON: its endpoints, parameters, request bodies, responses and authentication. Swagger UI turns that file into interactive documentation where developers can send test requests, and ReDoc renders the same file as a clean three-panel reference. In this tutorial you will write and validate an OpenAPI 3 spec, self-host both viewers as static files, and serve them with Nginx over HTTPS on Ubuntu 24.04, with a version selector for several API versions. ## Prerequisites To follow this tutorial, you will need: - A server running Ubuntu 24.04 LTS, for example a CubePath VPS, and a non-root user with `sudo` privileges. - A domain name with an A record pointing to the server. This guide uses `docs.your_domain`; replace it with your own hostname everywhere. - Ports 80 and 443 open to the Internet. No Node.js or build step is needed. Both viewers are plain static files. ## Step 1 - Installing Nginx and preparing the directories Install Nginx, the Certbot plugin for Nginx, and `pipx`, which you will use to install the validator: ```bash sudo apt update sudo apt install -y nginx python3-certbot-nginx pipx sudo ufw allow 'Nginx Full' ``` Create one directory per component under `/var/www/api-docs` and give your user ownership, so you can update the docs without `sudo`: ```bash sudo mkdir -p /var/www/api-docs/{swagger,redoc,specs/v1} sudo chown -R "$USER":"$USER" /var/www/api-docs ``` The final layout will be: | Path | Content | |---|---| | `/var/www/api-docs/specs/v1/openapi.yaml` | The OpenAPI document for version 1 of the API | | `/var/www/api-docs/swagger/` | Swagger UI static files | | `/var/www/api-docs/redoc/` | ReDoc page and script | ## Step 2 - Writing the OpenAPI specification The spec is the single source of truth: both viewers only display what it contains. Create a small but complete example with two endpoints, reusable schemas, error responses and API key authentication: ```bash nano /var/www/api-docs/specs/v1/openapi.yaml ``` ```yaml openapi: 3.0.3 info: title: Example API version: 1.0.0 description: | Manage the users of your account. Authenticate every request with your API key in the `X-API-Key` header. servers: - url: https://api.your_domain/v1 description: Production security: - ApiKeyAuth: [] tags: - name: Users description: User management paths: /users: get: tags: [Users] summary: List users operationId: listUsers parameters: - name: limit in: query description: Maximum number of users to return. schema: type: integer minimum: 1 maximum: 100 default: 20 responses: "200": description: A page of users. content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/User" total: type: integer example: 42 "401": $ref: "#/components/responses/Unauthorized" post: tags: [Users] summary: Create a user operationId: createUser requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateUser" responses: "201": description: The created user. content: application/json: schema: $ref: "#/components/schemas/User" "401": $ref: "#/components/responses/Unauthorized" /users/{userId}: get: tags: [Users] summary: Get a user operationId: getUser parameters: - name: userId in: path required: true schema: type: string example: usr_123 responses: "200": description: The requested user. content: application/json: schema: $ref: "#/components/schemas/User" "404": $ref: "#/components/responses/NotFound" components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key schemas: User: type: object required: [id, name, email] properties: id: type: string example: usr_123 name: type: string example: Alice Smith email: type: string format: email example: alice@example.com created_at: type: string format: date-time CreateUser: type: object required: [name, email] properties: name: type: string minLength: 2 maxLength: 100 email: type: string format: email Error: type: object properties: detail: type: string responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: "#/components/schemas/Error" NotFound: description: The resource does not exist. content: application/json: schema: $ref: "#/components/schemas/Error" ``` A few conventions make the rendered docs much more useful: a unique `operationId` per operation (code generators use it for method names), `example` values on schemas (Swagger UI uses them to prefill requests), and shared error responses under `components` so every endpoint documents them the same way. ## Step 3 - Validating the specification A spec with a broken `$ref` or a wrong field type renders as an error page or, worse, as silently incomplete docs. Install `openapi-spec-validator` in its own isolated environment with `pipx`: ```bash pipx install openapi-spec-validator pipx ensurepath ``` `pipx ensurepath` adds `~/.local/bin` to your `PATH`. Log out and back in, or open a new shell, then validate the file: ```bash openapi-spec-validator /var/www/api-docs/specs/v1/openapi.yaml ``` ```output /var/www/api-docs/specs/v1/openapi.yaml: OK ``` To see what an error looks like, change `$ref: "#/components/schemas/User"` to `$ref: "#/components/schemas/Usr"` in one place and run the validator again. It reports the unresolvable reference and exits with a non-zero code, which is what you want in a CI pipeline. Undo the change afterwards. ## Step 4 - Installing Swagger UI Swagger UI publishes a ready-to-serve `dist` folder in every release. Download the latest release and copy that folder into place: ```bash SWAGGER_UI_VERSION=$(curl -fsSL https://api.github.com/repos/swagger-api/swagger-ui/releases/latest | grep -Po '"tag_name": "v\K[^"]+') echo "$SWAGGER_UI_VERSION" curl -fsSL -o /tmp/swagger-ui.tar.gz "https://github.com/swagger-api/swagger-ui/archive/refs/tags/v${SWAGGER_UI_VERSION}.tar.gz" tar -xzf /tmp/swagger-ui.tar.gz -C /tmp cp -r "/tmp/swagger-ui-${SWAGGER_UI_VERSION}/dist/." /var/www/api-docs/swagger/ ``` The `echo` prints the version it found, for example `5.x.y`. The `dist` folder contains `index.html`, the JavaScript bundles, and `swagger-initializer.js`, which configures the page. By default it points to the public Petstore demo. Replace its contents: ```bash nano /var/www/api-docs/swagger/swagger-initializer.js ``` ```javascript window.onload = function () { window.ui = SwaggerUIBundle({ urls: [ { url: "/specs/v1/openapi.yaml", name: "v1" } ], "urls.primaryName": "v1", dom_id: "#swagger-ui", deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: "StandaloneLayout", persistAuthorization: true }); }; ``` The `urls` list fills the "Select a definition" drop-down in the top bar, which you will use for API versions in Step 7. `deepLinking` gives every operation a shareable URL, and `persistAuthorization` keeps the API key a developer enters in the browser across page reloads. Clean up the downloaded archive: ```bash rm -rf /tmp/swagger-ui.tar.gz "/tmp/swagger-ui-${SWAGGER_UI_VERSION}" ``` ## Step 5 - Installing ReDoc ReDoc ships as a single JavaScript file. Download version 2 from the jsDelivr CDN and serve it yourself, so the docs keep working if the CDN is unreachable and no third party sees your visitors: ```bash curl -fsSL -o /var/www/api-docs/redoc/redoc.standalone.js \ https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js ``` Create the page that loads it: ```bash nano /var/www/api-docs/redoc/index.html ``` ```html Example API reference ``` `expand-responses` opens the success responses by default and `required-props-first` lists required fields before optional ones, which makes long schemas easier to scan. ## Step 6 - Serving the docs with Nginx and HTTPS Create a server block that serves the whole directory: ```bash sudo nano /etc/nginx/sites-available/api-docs ``` ```nginx server { listen 80; listen [::]:80; server_name docs.your_domain; root /var/www/api-docs; index index.html; add_header X-Content-Type-Options nosniff always; add_header X-Frame-Options SAMEORIGIN always; location = / { return 302 /swagger/; } location /swagger/ { try_files $uri $uri/ =404; } location /redoc/ { try_files $uri $uri/ =404; } location /specs/ { types { application/yaml yaml yml; application/json json; } # Let other tools and sites load the spec, and always revalidate it add_header Access-Control-Allow-Origin "*" always; add_header Cache-Control "no-cache" always; add_header X-Content-Type-Options nosniff always; } } ``` Nginx's default MIME table has no entry for YAML, so the `types` block serves specs as `application/yaml` instead of a download. `Cache-Control: no-cache` makes browsers check for a new version on every load (a cheap request that usually returns `304 Not Modified`), so updated specs appear immediately. The `add_header` lines are repeated in `/specs/` because Nginx drops the server-level headers in any location that defines its own. Enable the site, check the configuration and reload: ```bash sudo ln -s /etc/nginx/sites-available/api-docs /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx ``` Request a Let's Encrypt certificate. Certbot adds the HTTPS server block and a redirect from HTTP to HTTPS, and renews the certificate automatically: ```bash sudo certbot --nginx -d docs.your_domain ``` Check that the spec is served with the right headers: ```bash curl -sI https://docs.your_domain/specs/v1/openapi.yaml ``` ```output HTTP/1.1 200 OK Server: nginx/1.24.0 (Ubuntu) Content-Type: application/yaml Access-Control-Allow-Origin: * Cache-Control: no-cache X-Content-Type-Options: nosniff ``` Open `https://docs.your_domain/` in a browser. It redirects to Swagger UI with the "Example API" definition and its Users operations. `https://docs.your_domain/redoc/` shows the same API in ReDoc. ## Step 7 - Publishing several API versions When you release a new major version, keep the old spec online until clients have migrated. Copy the current spec as the starting point for version 2: ```bash mkdir -p /var/www/api-docs/specs/v2 cp /var/www/api-docs/specs/v1/openapi.yaml /var/www/api-docs/specs/v2/openapi.yaml ``` In `specs/v2/openapi.yaml`, set `info.version` to `2.0.0` and the server URL to `https://api.your_domain/v2`. In `specs/v1/openapi.yaml`, mark the operations that are going away with `deprecated: true`, which both viewers display with a strike-through: ```yaml /users/{userId}: get: deprecated: true summary: Get a user description: Deprecated. Use `GET /v2/users/{userId}` instead. ``` Add the new version to Swagger UI's drop-down and make it the default: ```bash nano /var/www/api-docs/swagger/swagger-initializer.js ``` ```javascript urls: [ { url: "/specs/v2/openapi.yaml", name: "v2" }, { url: "/specs/v1/openapi.yaml", name: "v1 (deprecated)" } ], "urls.primaryName": "v2", ``` Validate both files, then reload the page in the browser. No Nginx reload is needed because only static files changed: ```bash openapi-spec-validator /var/www/api-docs/specs/v1/openapi.yaml /var/www/api-docs/specs/v2/openapi.yaml ``` ReDoc shows one spec per page, so create `redoc/v1.html` as a copy of `index.html` with `spec-url` pointing to the v1 file if you need both there too. ## Step 8 - Restricting access to internal docs (optional) Documentation for internal or partner APIs should not be public. Protect the site with HTTP basic authentication. Install the `htpasswd` tool and create a user, replacing `docs_user` with the name you want: ```bash sudo apt install -y apache2-utils sudo htpasswd -c /etc/nginx/.htpasswd-docs docs_user ``` Open the site file, which Certbot has extended with an HTTPS server block: ```bash sudo nano /etc/nginx/sites-available/api-docs ``` Add these two lines inside the server block that contains `listen 443 ssl`: ```nginx auth_basic "API documentation"; auth_basic_user_file /etc/nginx/.htpasswd-docs; ``` Test and reload Nginx, then confirm that anonymous requests are refused: ```bash sudo nginx -t && sudo systemctl reload nginx curl -s -o /dev/null -w "%{http_code}\n" https://docs.your_domain/swagger/ ``` ```output 401 ``` ## Troubleshooting **Swagger UI shows "Failed to load API definition"**: the browser could not fetch or parse the spec. Open the spec URL directly, check that it returns 200, and run `openapi-spec-validator` on it. A 404 usually means the path in `swagger-initializer.js` does not match the file on disk. **"Try it out" fails with "Failed to fetch" or a CORS error in the browser console**: the requests go from the docs domain to your API domain, so the API must answer with CORS headers that allow `https://docs.your_domain`, including for `OPTIONS` preflight requests and the `X-API-Key` header. Configure that in the API or its reverse proxy, not in the docs server. **The page still shows the Petstore demo**: the browser cached the old `swagger-initializer.js`. Force a reload, and confirm that you edited the file under `/var/www/api-docs/swagger/`. **`openapi-spec-validator: command not found`**: `~/.local/bin` is not in your `PATH` yet. Open a new shell after `pipx ensurepath`, or run `~/.local/bin/openapi-spec-validator` directly. ## Conclusion You wrote and validated an OpenAPI specification, self-hosted Swagger UI and ReDoc, served them from Nginx over HTTPS with correct headers for the spec files, and published two API versions side by side. From here you can generate the spec from your framework (FastAPI, NestJS and Spring all export OpenAPI) instead of writing it by hand, run `openapi-spec-validator` in CI before copying new specs to the server with `rsync`, and generate client SDKs from the same file with OpenAPI Generator.