How to generate API documentation from OpenAPI

To generate API documentation from an OpenAPI spec, you typically use a docs generator that reads your openapi.yaml or openapi.json and renders a website or static docs.

Common tools

1) Swagger UI

Best for interactive API docs.

Install / use

• Self-host via npm, Docker, or embed in your app.
• Point it at your OpenAPI file.

Example

<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
<script>
  SwaggerUIBundle({
    url: "/openapi.yaml",
    dom_id: "#swagger-ui"
  });
</script>

2) Redoc / Redocly

Best for clean, readable reference docs.

Example

<redoc spec-url="/openapi.yaml"></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>

3) OpenAPI Generator

Good if you want generated docs plus client/server code.

CLI example

openapi-generator-cli generate -i openapi.yaml -g html2 -o docs/

4) Stoplight Elements

Useful if you want interactive and styled docs.

---

Typical workflow

1. Write or export your OpenAPI spec

   • openapi.yaml or openapi.json

2. Validate the spec

   • Use:

     swagger-cli validate openapi.yaml
     

   • Or:

     openapi-generator-cli validate -i openapi.yaml
     

3. Generate docs

   • Swagger UI, Redoc, OpenAPI Generator, etc.

4. Publish

   • Host the generated static site on:
     • GitHub Pages
     • Netlify
     • Vercel
     • S3 / CloudFront
     • Your web server

---

Example with Redocly CLI

If you want a simple static site:

npm install -g @redocly/cli
redocly build-docs openapi.yaml -o docs/index.html

Then open docs/index.html or deploy that folder.

---

Example with Swagger UI in Docker

docker run -p 8080:8080 \
  -e SWAGGER_JSON=/foo/openapi.yaml \
  -v $(pwd)/openapi.yaml:/foo/openapi.yaml \
  swaggerapi/swagger-ui

Then visit http://localhost:8080.

---

Best practice

• Keep the OpenAPI spec in source control.
• Generate docs automatically in CI/CD.
• Validate the spec on every commit.
• Publish docs on every release.

If you want, I can also show you:

1. how to generate docs from OpenAPI using Python, Node.js, or Java, or
2. how to set up auto-generated docs in GitHub Actions.