OpenAPI Generator API Documentation: Generate Interactive Doc Sites
In this tutorial, you will learn about OpenAPI Generator API Documentation: Generate Interactive Doc Sites. We cover key concepts, practical examples, and best practices to help you master this topic.
OpenAPI Generator produces API documentation in multiple formats including interactive HTML (Redoc, SwaggerUI), static Markdown for static site generators, AsciiDoc for PDF generation, and Postman collections.
What You'll Learn
How to generate API documentation from OpenAPI specs: interactive HTML with Redoc/SwaggerUI, Markdown for static sites (Hugo, Docusaurus), AsciiDoc for PDF, customize doc templates, and deploy doc sites to Netlify/GitHub Pages.
Why It Matters
Good API documentation is essential for adoption. Generating docs from the spec ensures they stay in sync with the API. DodaTech publishes interactive HTML docs and Markdown docs for tutorials.dodatech.com from the same spec.
Real-World Use
The DodaTech API team updates the spec with a new endpoint. CI generates interactive HTML docs (hosted on api.dodatech.com/docs) and Markdown docs (published to tutorials.dodatech.com) — both updated within 5 minutes.
flowchart LR
A["OpenAPI\nSpec"] --> B["Documentation\nGenerator"]
B --> C["HTML\nRedoc/SwaggerUI"]
B --> D["Markdown\nStatic Site"]
B --> E["AsciiDoc\nPDF"]
B --> F["Postman\nCollection"]
C --> G["Deploy to\nNetlify"]
D --> H["Deploy to\nHugo Site"]
style A fill:#6cb4ee,color:#fff
style C fill:#bbf7d0,stroke:#16a34a
style D fill:#dbeafe,stroke:#2563eb
Generating HTML Docs with Redoc
# Generate HTML docs with Redoc
openapi-generator generate \
-i openapi.yaml \
-g html \
-o ./docs-html \
--additional-properties=appName="DodaTech API"
# Generate with Redoc theme (better UI)
openapi-generator generate \
-i openapi.yaml \
-g html2 \
-o ./docs-html2
# Generated structure:
# ./docs-html2/
# index.html # Interactive Redoc page
# openapi.yaml # Original spec (bundled)
#
# Open index.html in a browser to see interactive docs
<!-- Generated index.html includes Redoc CDN -->
<!DOCTYPE html>
<html>
<head>
<title>DodaTech API</title>
<!-- Redoc CDN for rendering -->
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
<style>
body { margin: 0; padding: 0; }
</style>
</head>
<body>
<redoc spec-url='openapi.yaml'></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>
Generating Markdown Documentation
# Generate Markdown docs for static site generators
openapi-generator generate \
-i openapi.yaml \
-g markdown \
-o ./docs-markdown
# Generated structure:
# ./docs-markdown/
# Apis/
# UsersApi.md # Endpoint documentation
# ProductsApi.md
# OrdersApi.md
# Models/
# User.md # Schema documentation
# Order.md
# Error.md
# README.md # Index page
<!-- Generated Apis/UsersApi.md -->
# Users API
## `GET /users` — List Users
### Description
Returns a paginated list of users.
### Parameters
| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| limit | query | integer | false | Number of results per page (default 20) |
| offset | query | integer | false | Number of results to skip (default 0) |
### Response `200`
```json
[
{
"id": 1,
"email": "user@example.com",
"name": "User Name",
"role": "admin",
"created_at": "2026-06-28T12:00:00Z"
}
]
Response 401
{
"error": "Unauthorized",
"message": "Invalid or expired token"
}
## SwaggerUI Generation
```bash
# Generate SwaggerUI documentation
# SwaggerUI is not a built-in generator, but you can create it:
# 1. Download SwaggerUI
wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v5.17.0.zip
unzip v5.17.0.zip
# 2. Copy spec into SwaggerUI
cp openapi.yaml swagger-ui-5.17.0/dist/
# 3. Update swagger-initializer.js to point to your spec
# url: "./openapi.yaml",
# 4. Deploy the dist/ directory
# The SwaggerUI reads the spec from openapi.yaml
AsciiDoc Generation
# Generate AsciiDoc for PDF generation
openapi-generator generate \
-i openapi.yaml \
-g asciidoc \
-o ./docs-asciidoc
# Convert to PDF with asciidoctor
asciidoctor-pdf docs-asciidoc/index.adoc -o api-documentation.pdf
# Expected: Generated api-documentation.pdf
Deploying Documentation
# .github/workflows/deploy-docs.yml
name: Deploy API Docs
on:
push:
branches: [main]
paths:
- 'openapi.yaml'
- 'docs/**'
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Generate HTML Docs
run: |
openapi-generator generate \
-i openapi.yaml \
-g html2 \
-o docs/html
- name: Generate Markdown Docs
run: |
openapi-generator generate \
-i openapi.yaml \
-g markdown \
-o docs/markdown
- name: Deploy to Netlify
uses: nwtgck/actions-netlify@v3
with:
publish-dir: docs/html
production-branch: main
github-token: ${{ secrets.GITHUB_TOKEN }}
Common Mistakes
1. Not Updating Docs When the Spec Changes
Docs get stale fast. Set up CI to regenerate docs automatically when the spec file changes. Add a spec change trigger in the CI pipeline.
2. Using Only One Doc Format
Different users prefer different formats. Developers want interactive SwaggerUI/Redoc. Static site readers want Markdown. PDF users need AsciiDoc. Generate multiple formats from the same spec.
3. Not Customizing the Doc Theme
Default Redoc/SwaggerUI themes are generic. Customize colors, logo, and branding to match your company identity. Set appName, theme properties, and custom CSS.
4. Missing Descriptions in the Spec
Documentation quality depends on the spec quality. Endpoints and models without description fields generate empty documentation. Write thorough descriptions in the spec.
5. Serving Spec File Directly to Users
The raw openapi.yaml is useful but not user-friendly. Generate at least HTML docs that render the spec interactively. Raw YAML is for developers, not end users.
Practice Questions
- What documentation formats can OpenAPI Generator produce?
- How is HTML2 different from HTML generator?
- How do you keep documentation in sync with the API?
- How do you deploy generated docs?
Answers:
- HTML (Redoc), HTML2 (SwaggerUI-style), Markdown, AsciiDoc, Postman Collection (via openapi-to-postman). Each targets different audiences: interactive, static site, PDF, Postman users.
- HTML uses basic SwaggerUI. HTML2 uses Redoc with a cleaner, more modern UI, better navigation, and code samples. HTML2 is recommended for new projects.
- Automate doc generation in CI when the spec changes. Use a GitHub Action that regenerates and deploys docs on every push to the spec file. Never edit docs manually.
- Deploy HTML docs to static hosting: Netlify, GitHub Pages, Vercel, S3+CloudFront. Deploy Markdown to your static site generator (Hugo, Docusaurus). Deploy AsciiDoc as PDF download.
Challenge: Write an OpenAPI spec with 8 endpoints and thorough descriptions, generate HTML2 (Redoc), Markdown, and AsciiDoc docs, customize the HTML theme with your branding, deploy the HTML docs to Netlify, integrate the Markdown docs into a Hugo site, and set up CI to auto-regenerate on spec changes.
FAQ
Mini Project
Create an OpenAPI spec for a Library API (8 endpoints, 5 models) with thorough descriptions, generate HTML2 docs with custom branding, Markdown docs for static site integration, and AsciiDoc for PDF, deploy the HTML docs to GitHub Pages, and set up CI auto-generation.
What's Next
Configuration & Customization — customize OpenAPI Generator output.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro