--- title: "Generate API Documentation from OpenAPI: A Step-by-Step Guide" description: "Generate beautiful, interactive API documentation from your OpenAPI spec — tools comparison, setup guide, and best practices for keeping docs in sync with your API." canonicalUrl: "https://zuplo.com/learning-center/generate-api-documentation-openapi" pageType: "learning-center" authors: "nate" tags: "OpenAPI, API Documentation" image: "https://zuplo.com/og?text=Generate%20API%20Documentation%20from%20OpenAPI%3A%20A%20Step-by-Step%20Guide" --- 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](https://zudoku.dev) 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 | Feature | Zudoku | Redoc | Swagger UI | Stoplight Elements | ReadMe | | ---------------------- | ------------------ | --------- | ---------- | ------------------ | ------- | | **Open Source** | Yes | Yes | Yes | Yes | No | | **Try-It Playground** | Yes | Paid only | Yes | Yes | Yes | | **Theming** | Yes | Limited | Limited | Yes | Yes | | **API Key Management** | Yes (with Zuplo) | No | No | No | Yes | | **Hosting** | Self-host or Zuplo | Self-host | Self-host | Self-host | Managed | ## 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: ```bash 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: ```typescript 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: ```typescript 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`: ```typescript 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: ```bash 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: ```bash # 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](https://zuplo.com) 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](https://portal.zuplo.com/signup) and create a new project, or use the CLI: ```bash 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: ```json { "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): ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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: ```yaml 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](https://github.com/stoplightio/spectral) to validate your OpenAPI spec in CI. Catch missing descriptions, invalid schemas, and breaking changes before they merge: ```bash 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](https://github.com/Tufin/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](https://zudoku.dev). 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](https://zuplo.com) 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.