Generate API Documentation from OpenAPI: A Step-by-Step Guide

Your OpenAPI spec is the single source of truth for your API. It defines every endpoint, every parameter, every request and response schema. When you generate documentation directly from that spec, your docs are always accurate and always in sync with your actual API behavior. No more stale docs. No more copy-and-paste errors. No more "the docs say X but the API does Y" support tickets.

In this guide, you will learn why generating docs from OpenAPI is the right approach, compare the most popular tools for doing it, walk through setup with two different tools, and pick up best practices for keeping everything in sync long-term.

Why Generate Docs from OpenAPI

Writing API documentation by hand is a losing battle. APIs evolve constantly -- new endpoints get added, request bodies change, authentication requirements shift. Manual docs fall out of date the moment someone merges a PR that changes the API without updating the docs.

Generating documentation from your OpenAPI spec solves this by design:

• Always in sync. The spec is the documentation source. When the spec changes, the docs change automatically.
• Interactive try-it playground. Most doc generators include a built-in API explorer where developers can make real requests against your API without leaving the docs.
• Consistent formatting. Every endpoint follows the same layout -- summary, parameters, request body, responses, examples. No inconsistencies between endpoints written by different team members.
• Reduced maintenance. You maintain one artifact (the OpenAPI spec) instead of two (the spec and a separate docs site).
• Machine-readable for tooling. The same spec that powers your docs can also drive SDK generation, mock servers, API testing, and gateway configuration.

If you already have an OpenAPI spec -- or you are willing to write one -- you are 90% of the way to having great API documentation.

Tools for Generating API Docs

There are several tools that can turn an OpenAPI spec into a documentation site. Here is a brief comparison of the most popular options.

Zudoku (by Zuplo)

Zudoku is an open-source, React-based documentation framework built specifically for API documentation. It reads your OpenAPI spec and generates a full documentation site with a built-in try-it playground, search, theming, and navigation -- all out of the box. Zudoku powers Zuplo's developer portal and is free to use.

Redoc

Redoc is a popular open-source OpenAPI renderer known for its clean three-panel layout. It produces beautiful static documentation, but the free version has limited interactivity -- there is no built-in try-it console unless you upgrade to the commercial version.

Swagger UI

Swagger UI is the original OpenAPI documentation tool. It is open-source and functional, but the design feels dated compared to newer alternatives. It does include a basic try-it feature for making API calls directly from the docs.

Stoplight Elements

Stoplight Elements provides React components for embedding API documentation into existing sites. It is customizable and supports OpenAPI 3.x, but requires more setup and configuration than standalone tools.

ReadMe

ReadMe is a SaaS platform that generates interactive API documentation with built-in analytics, versioning, and developer dashboards. It is polished but not open-source, and pricing scales with usage.

Comparison Table

Step-by-Step: Generate Docs with Zudoku

Zudoku is the fastest way to go from an OpenAPI spec to a deployed documentation site. Here is how to set it up.

Step 1: Install Zudoku

Scaffold a new Zudoku project using the CLI:

npx create-zudoku-app my-docs
cd my-docs

The CLI will prompt you for basic configuration options. Once it finishes, you will have a ready-to-run documentation project.

Step 2: Add Your OpenAPI Spec

Place your OpenAPI spec file in the project. Zudoku supports both JSON and YAML formats. You can reference a local file or a remote URL in the configuration.

Edit zudoku.config.tsx to point to your spec:

import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  apis: [
    {
      type: "file",
      input: "./openapi.json",
      navigationId: "api",
    },
  ],
};

export default config;

If your spec is hosted at a URL (for example, from your API gateway), you can reference it directly:

apis: [
  {
    type: "url",
    input: "https://api.example.com/openapi.json",
    navigationId: "api",
  },
];

Step 3: Configure Navigation and Branding

Customize the top navigation, sidebar, and theme in zudoku.config.tsx:

const config: ZudokuConfig = {
  topNavigation: [
    { id: "api", label: "API Reference" },
    { id: "docs", label: "Documentation" },
  ],
  theme: {
    light: {
      primary: "#6366f1",
    },
    dark: {
      primary: "#818cf8",
    },
  },
  apis: [
    {
      type: "file",
      input: "./openapi.json",
      navigationId: "api",
    },
  ],
};

Step 4: Run Locally

Start the development server to preview your docs:

npm run dev

Open http://localhost:9000 in your browser. You should see your full API documentation rendered from the OpenAPI spec, complete with the try-it playground for every endpoint.

Step 5: Deploy

Zudoku builds to static files, so you can deploy it anywhere. For the simplest deployment options:

# Build for production
npm run build

# Deploy to Vercel
npx vercel

# Or deploy to Netlify
npx netlify deploy --prod

You can also deploy Zudoku as part of a Zuplo project for integrated API gateway and documentation hosting.

Step-by-Step: Generate Docs with Zuplo

If you are using Zuplo as your API gateway, documentation generation is built in. Your OpenAPI spec is your gateway configuration, so your docs are always in sync by default.

Step 1: Create a Zuplo Project

Sign up at portal.zuplo.com and create a new project, or use the CLI:

npx create-zuplo-api@latest my-api
cd my-api

Step 2: Add Your Routes

Define your API routes in config/routes.oas.json. This file is a standard OpenAPI 3.1 document that also serves as your gateway configuration:

{
  "openapi": "3.1.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "List all users",
        "description": "Returns a paginated list of users.",
        "operationId": "listUsers",
        "tags": ["Users"],
        "responses": {
          "200": {
            "description": "A list of users"
          }
        }
      }
    }
  }
}

Step 3: Docs Are Automatically Generated

When you deploy your Zuplo project, a developer portal is automatically generated from your routes.oas.json file. There is no extra build step or separate deployment -- the docs are part of your API deployment.

Every route in your gateway configuration appears in the developer portal with its summary, description, parameters, request/response schemas, and a try-it console.

Step 4: Customize the Developer Portal

You can customize the portal's branding, authentication, and content through the Zuplo dashboard. Add custom pages, configure API key self-service, and set up authentication so developers can test with their own keys directly from the docs.

OpenAPI Best Practices for Better Docs

The quality of your generated documentation depends entirely on the quality of your OpenAPI spec. Here are the practices that make the biggest difference.

Write Clear Summaries and Descriptions

Every operation should have both a summary (short, used in navigation) and a description (detailed, shown on the endpoint page):

paths:
  /users/{id}:
    get:
      summary: Get a user by ID
      description: |
        Retrieves a single user by their unique identifier.
        Returns 404 if the user does not exist.

Include Request and Response Examples

Examples make your docs immediately useful. Developers can see exactly what to send and what to expect back:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "usr_abc123"
        name:
          type: string
          example: "Jane Smith"
        email:
          type: string
          example: "jane@example.com"

Use Tags to Organize Endpoints

Tags group related endpoints in the documentation sidebar. Without tags, developers see a flat list of every endpoint:

tags:
  - name: Users
    description: User management operations
  - name: Billing
    description: Subscription and payment operations

Define Reusable Schemas

Use components/schemas to define objects once and reference them everywhere. This keeps your spec DRY and ensures consistent documentation across endpoints:

components:
  schemas:
    PaginatedResponse:
      type: object
      properties:
        data:
          type: array
        has_more:
          type: boolean
        next_cursor:
          type: string

Add Server URLs

The servers field tells the try-it playground where to send requests. Without it, developers cannot test your API from the docs:

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://api-staging.example.com/v1
    description: Staging

Keeping Docs in Sync

Generating docs from OpenAPI only works if the spec stays accurate. Here are CI/CD patterns that prevent drift.

Validate on every PR. Use a linting tool like Spectral to validate your OpenAPI spec in CI. Catch missing descriptions, invalid schemas, and breaking changes before they merge:

npx @stoplight/spectral-cli lint openapi.json

Auto-deploy on merge. Connect your documentation deployment to your main branch. When a PR merges that changes the OpenAPI spec, the docs rebuild and deploy automatically. Both Zudoku (via Vercel/Netlify) and Zuplo handle this natively with Git-based deployments.

Generate the spec from code. If you use a framework that can produce an OpenAPI spec at build time (FastAPI, NestJS with Swagger plugin, .NET with Swashbuckle), generate the spec as a build artifact rather than maintaining it by hand. This eliminates the possibility of the spec and the code diverging.

Diff the spec in code review. Tools like oasdiff can show you exactly what changed in an OpenAPI spec between two versions, making it easier to review API changes in pull requests.

Get Started

If you want a standalone open-source documentation site, start with Zudoku. It takes five minutes to go from an OpenAPI spec to a fully themed, interactive documentation site.

If you want documentation that is tightly integrated with your API gateway -- with built-in API key management, analytics, and rate limiting -- Zuplo's developer portal generates docs automatically from your gateway configuration with zero extra setup.

Either way, the principle is the same: write the spec once, generate everything else from it.