How do I generate API docs from an OpenAPI file?

You can generate API documentation from an OpenAPI file in a few common ways, depending on whether you want a static site, a hosted docs page, or docs in your app.

1) Use Swagger UI

Swagger UI renders an OpenAPI file into interactive docs.

Quick example with Docker

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

Then open:

• http://localhost:8080

Notes

• Works with openapi.json or openapi.yaml
• Gives “try it out” support for endpoints

---

2) Use Redoc

Redoc generates clean, readable API reference docs.

CLI / static HTML

If you have Node.js:

npx redocly build-docs openapi.yaml -o docs.html

Open docs.html in a browser.

If using Redocly

Redocly also supports:

• linting
• bundling
• publishing docs

---

3) Generate docs with OpenAPI Generator

OpenAPI Generator can create documentation artifacts and client/server code.

Example

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

This produces HTML docs you can host.

---

4) Host docs in a docs site

You can integrate OpenAPI docs into:

• MkDocs
• Docusaurus
• GitHub Pages
• Read the Docs

Common pattern:

1. Store openapi.yaml
2. Build docs with Redoc/Swagger UI
3. Publish the generated static files

---

5) Use tools from your language/framework

Many ecosystems have OpenAPI doc generators or viewers:

• FastAPI: auto-generates Swagger UI and ReDoc
• Spring Boot: springdoc-openapi
• ASP.NET Core: Swashbuckle
• Node.js: express-openapi, swagger-ui-express

---

Recommended choices

• Interactive API explorer: Swagger UI
• Polished reference docs: Redoc
• Generate docs + other outputs: OpenAPI Generator

If you want, I can give you:

1. a one-command setup for your environment, or
2. a GitHub Actions workflow to auto-publish docs from openapi.yaml.