Your API is only as good as its documentation. Developers judge your API by the quality of its reference docs — can they find endpoints quickly, see example requests and responses, and try things out interactively? OpenAPI (formerly Swagger) provides the specification, but you need a renderer to turn that spec into human-readable documentation.

This guide compares three leading self-hosted OpenAPI documentation renderers: Scalar, Redoc, and RapiDoc. We cover how each tool renders your API spec, provide Docker Compose deployment configs, and help you choose the right renderer for your API documentation workflow.

Why Self-Host API Documentation?

Cloud-hosted API documentation services like ReadMe, Stoplight, and Postman lock your docs behind paywalls and vendor accounts. Self-hosted renderers give you full control — your docs live on your infrastructure, behind your domain, with no per-request limits or usage caps.

Self-hosted API docs are also essential for internal APIs that should never be exposed to third-party services. When you are documenting authentication endpoints, internal microservice contracts, or financial APIs, keeping the documentation renderer in your own network is a security requirement.

Scalar API Documentation

Scalar is a modern, open-source API reference renderer that supports OpenAPI, Swagger, and Postman collections. It provides a clean, modern interface with an integrated API client, dark mode, and embeddable components.

Scalar Docker Compose

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

version: "3.8"
services:
  scalar:
    image: node:20-alpine
    ports:
      - "5050:5050"
    volumes:
      - ./openapi.yaml:/app/openapi.yaml:ro
    working_dir: /app
    command: >
      sh -c "npx @scalar/cli@latest serve openapi.yaml --port 5050 --host 0.0.0.0"
    networks:
      - api-docs-net

networks:
  api-docs-net:
    driver: bridge

Alternatively, build a static site and serve it with any web server:

1
2

npx @scalar/cli@latest build openapi.yaml --output ./dist
# Serve with Nginx, Caddy, or any static file server

Scalar features:

FeatureDetails
Spec supportOpenAPI 3.0, 3.1, Swagger 2.0
Interactive testingBuilt-in API client for trying endpoints
ThemesMultiple built-in themes, customizable CSS
Framework integrationsFastAPI, Express, Hono, Nitro, Docusaurus
CDN/EmbeddableScript tag embed, iframe, or full page
GitHub stars14,888
Last updated2026-05-01

Redoc API Documentation

Redoc is the most widely adopted open-source OpenAPI renderer. It generates a three-panel layout (navigation, operations, examples) from your OpenAPI spec. Redoc is used by Stripe, AWS, and hundreds of other API providers.

Redoc Docker Compose

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

version: "3.8"
services:
  redoc:
    image: redocly/redoc:latest
    ports:
      - "8080:80"
    environment:
      - SPEC_URL=/openapi.yaml
    volumes:
      - ./openapi.yaml:/usr/share/nginx/html/openapi.yaml:ro
    networks:
      - api-docs-net

networks:
  api-docs-net:
    driver: bridge

Or generate static HTML:

1
2

npx redoc-cli bundle openapi.yaml -o docs/index.html
# Deploy docs/ to any static web server

Redoc features:

FeatureDetails
Spec supportOpenAPI 3.0, 3.1, Swagger 2.0
LayoutThree-panel (nav, operations, examples)
Code samplesAuto-generated for multiple languages
BrandingCustom logo, colors, fonts via theme config
PerformanceHandles specs with 1000+ endpoints
GitHub stars25,666
Last updated2026-02-07

RapiDoc API Documentation

RapiDoc is a Web Component for rendering OpenAPI specs. It provides a single HTML element that you can embed anywhere. RapiDoc supports all OpenAPI features plus additional capabilities like markdown descriptions, authentication UI, and schema diagrams.

RapiDoc Docker Compose

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

version: "3.8"
services:
  rapidoc:
    image: mrin9/rapiddoc:latest
    ports:
      - "8080:80"
    volumes:
      - ./openapi.yaml:/usr/share/nginx/html/openapi.yaml:ro
    networks:
      - api-docs-net

networks:
  api-docs-net:
    driver: bridge

Or use the HTML embed approach:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<!DOCTYPE html>
<html>
<head>
  <script type="module" src="https://unpkg.com/rapiddoc/dist/rapiddoc-min.js"></script>
</head>
<body>
  <rapi-doc spec-url="/openapi.yaml"
    theme="dark"
    show-header="true"
    render-style="focused">
  </rapi-doc>
</body>
</html>

RapiDoc features:

FeatureDetails
Spec supportOpenAPI 3.0, 3.1, Swagger 2.0
Web ComponentEmbed as <rapi-doc> element anywhere
Auth UIBuilt-in authentication forms (Basic, Bearer, API Key, OAuth2)
DiagramsSchema visualization with entity-relationship diagrams
MarkdownFull markdown support in descriptions
GitHub stars1,889
Last updated2026-02-11

Comparison: API Documentation Renderers

FeatureScalarRedocRapiDoc
OpenAPI 3.1 supportYesYesYes
Swagger 2.0 supportYesYesYes
Interactive API clientYes (built-in)NoYes (try-it panel)
Three-panel layoutYesYesConfigurable
Dark modeYesVia theme configYes
EmbeddableScript tag, iframe, componentReact componentWeb Component
Static site generationYes (CLI build)Yes (redoc-cli bundle)HTML embed only
Custom themingCSS variablesTheme config objectHTML attributes
Performance (large specs)GoodExcellent (handles 1000+ endpoints)Good
Community adoptionGrowing rapidlyIndustry standardNiche but capable
GitHub stars14,88825,6661,889
Last updated2026-05-012026-02-072026-02-11

Managing API Versions with Self-Hosted Docs

A common pattern for self-hosted API documentation is to serve multiple versions side by side:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

version: "3.8"
services:
  docs-v1:
    image: redocly/redoc:latest
    ports:
      - "8081:80"
    environment:
      - SPEC_URL=/openapi-v1.yaml
    volumes:
      - ./specs/v1/openapi.yaml:/usr/share/nginx/html/openapi-v1.yaml:ro

  docs-v2:
    image: redocly/redoc:latest
    ports:
      - "8082:80"
    environment:
      - SPEC_URL=/openapi-v2.yaml
    volumes:
      - ./specs/v2/openapi.yaml:/usr/share/nginx/html/openapi-v2.yaml:ro

  docs-latest:
    image: scalar/cli:latest
    ports:
      - "8080:5050"
    volumes:
      - ./specs/latest/openapi.yaml:/app/openapi.yaml:ro
    command: ["npx", "@scalar/cli@latest", "serve", "openapi.yaml", "--port", "5050", "--host", "0.0.0.0"]

This approach lets you maintain documentation for legacy API versions while showcasing the latest version prominently. Each version gets its own container, spec file, and URL path.

Why Self-Host API Documentation?

Beyond security and cost, self-hosted API documentation gives you full control over the developer experience. You can integrate docs with your internal wiki, add custom authentication, embed interactive tutorials, and version documentation alongside your API releases.

When you use cloud documentation platforms, you are limited to the features they offer and the pricing tiers they set. Self-hosted renderers are free, open-source, and fully customizable. You can modify the source code, add custom plugins, and integrate with your CI/CD pipeline to auto-generate docs on every API release.

For API management guides, see our Openapi Generator Vs Swagger Codegen Vs Jhipste…. For API schema validation, check our Openapi Generator Vs Swagger Codegen Vs Jhipste…, and Self Hosted Api Documentation Generators Swagge….

API Documentation Best Practices for Self-Hosted Stacks

Beyond choosing a renderer, there are several practices that make self-hosted API documentation more effective:

Keep your OpenAPI spec in version control. Store your openapi.yaml file alongside your source code. This ensures documentation changes are reviewed in the same pull requests as code changes. Tools like Spectral can lint your spec in CI to catch errors before they reach production.

Use relative references for your spec URL. Instead of hardcoding https://api.example.com/openapi.yaml, use a relative path like /openapi.yaml. This makes it easy to move your docs between environments (staging, production) without changing configuration.

Add x-codeSamples extensions. Many renderers support custom extensions that add code examples in multiple languages. Add x-codeSamples to your operations to show curl, Python, JavaScript, and Go examples directly in the documentation.

Set up automated spec publishing. Use a CI pipeline to validate your OpenAPI spec on every merge to main, then automatically deploy the rendered docs. This eliminates the gap between API changes and documentation updates.

Enable CORS on your API for the docs domain. If your API client tries endpoints directly from the docs page, the browser needs CORS headers. Add Access-Control-Allow-Origin headers to your API responses so the interactive client can reach your endpoints.

FAQ

What is the difference between OpenAPI and Swagger?

OpenAPI is the current name for the API specification formerly known as Swagger. Swagger 2.0 was rebranded as OpenAPI 3.0 in 2017. The Swagger tooling ecosystem (Swagger UI, Swagger Editor) has largely been superseded by OpenAPI-native renderers like Redoc, Scalar, and RapiDoc.

Which API documentation renderer should I choose?

Redoc is the safest choice — it is the most widely adopted, handles large specs well, and is used by major API providers. Scalar is the best choice if you want a modern interface with a built-in API client. RapiDoc is ideal if you need a lightweight embeddable web component with authentication UI.

Can I host multiple API versions with these tools?

Yes. Each renderer can be deployed as a separate Docker container, each serving a different version of your OpenAPI spec. Route traffic through a reverse proxy with version-based paths (for example, /docs/v1/, /docs/v2/, /docs/latest/) so developers can access the documentation for the API version they are using.

Do these tools support Swagger 2.0 specs?

All three renderers support Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1 specifications. However, Redoc and Scalar have the best OpenAPI 3.1 support, including support for webhooks and the latest JSON Schema draft features.

Can I generate static HTML from my OpenAPI spec?

Redoc supports static generation through redoc-cli bundle. Scalar supports static generation through its CLI build command. RapiDoc uses an HTML embed approach where you include the Web Component script tag and point it at your spec URL. For fully offline static sites, Redoc and Scalar are the better choices.

How do I integrate API docs into my CI/CD pipeline?

Add a build step that runs the renderer CLI after your OpenAPI spec is updated. For Redoc, run redoc-cli bundle to generate static HTML. For Scalar, run scalar build to generate a static site. Commit the output to your docs branch or deploy to your web server. This ensures your documentation is always in sync with your API spec.