Swagger UI

Last reviewed Aug 26, 2026 · 776 words

Swagger UI is a few megabytes of static HTML and JavaScript that reads an OpenAPI file and turns it into a clickable console. Hosting it is the least difficult thing you will do this month: a 128 MB container or a folder behind any web server. The one thing that reliably goes wrong is the browser. The try-it-out button sends requests from the docs' origin to your API's origin, and if the API does not answer CORS preflights, every button returns a network error and someone files a ticket that the API is down. Sort that out before you polish anything else.

Three ways to serve it, ranked by effort

The container is the quickest. Mount your spec and name it:

services:
  docs:
    image: swaggerapi/swagger-ui
    ports:
      - "8080:8080"
    environment:
      - SWAGGER_JSON=/spec/openapi.yaml
    volumes:
      - ./openapi.yaml:/spec/openapi.yaml:ro

SWAGGER_JSON_URL points it at a spec served elsewhere instead, and the URLS variable takes a JSON list for a dropdown of several APIs. Second option: copy the dist folder from the release and edit the url in swagger-initializer.js; it then serves from Caddy or any file server with no runtime at all. Third, and usually best: let the framework do it. FastAPI ships Swagger UI at /docs automatically, springdoc does the same for Spring, swaggo for Go. If your API already has a /docs route, a separate deployment adds a second thing to keep in sync for no gain.

CORS is the wall, and same-origin is the door

The tidy fix is to make the docs and the API the same origin, so preflights never happen. A reverse proxy does it with path routing:

api.example.com {
    handle /docs* {
        reverse_proxy swagger-ui:8080
    }
    handle {
        reverse_proxy api:9000
    }
}

If the docs must live on a different host, the API has to return Access-Control-Allow-Origin for the docs origin and answer OPTIONS requests; most frameworks have a one-line middleware for it. Two related details: the servers: block in the spec decides where try-it-out sends requests, and a spec generated on a developer's laptop often still says http://localhost:8000; and an API behind HTTPS will refuse mixed-content calls from docs served over HTTP, so put TLS on both.

Docs are an attack surface, so gate them like one

An OpenAPI file is a complete map of your endpoints, parameters and auth schemes. For an internal service that is exactly the information you do not want indexed. Serve the docs behind the same authentication as the API, or on the Tailscale side only, and disable the auto-generated /docs route in production for anything not meant to be public. Swagger UI's "Authorize" dialog stores tokens in the page's memory, which is fine, but people paste production credentials into it on shared screens, which is not.

The spec is the product; the renderer is 10 minutes

The tool is only as good as the file it renders. Specs written by hand drift from the code within a month; specs generated from code annotations stay honest. Lint with Spectral in CI so a broken $ref fails the build instead of rendering as a blank section. Large specs are the other real limitation: a 3,000-endpoint file makes the page take 10 or more seconds to paint, and the cure is docExpansion: "none" in the initializer plus splitting the API into several smaller documents behind that URLS dropdown.

Redoc and Hoppscotch cover what it does not

Swagger UI is a console that reads like documentation. Redoc is documentation that reads well and has no console; for a public reference page it looks better and loads faster. Neither is an API client. If what you actually want is Postman without the account, that is Hoppscotch, which imports the same OpenAPI file and adds collections, environments and history; the Postman alternatives page lays out that choice. Run Swagger UI for interactive exploration by people who already know the API, Redoc for people reading it for the first time, and Hoppscotch for the person testing it every day.

What I'd do

Use the framework's built-in /docs route wherever it exists, put it on the same origin as the API behind the reverse proxy, and protect it with the same auth as the API. Deploy the standalone container only for APIs you do not control, pointed at a spec you generate in CI and lint before publishing. Total operational cost, once the CORS question is settled: none, which is the right amount for a static folder.