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