How to auto-generate API documentation from an OpenAPI spec with GitBook

Keeping API documentation up to date is one of those jobs that sounds straightforward until multiple teams get involved.

With engineers updating the OpenAPI spec, writers improving guides and examples, and product teams wanting documentation published quickly, it’s easy for documentation updates to become “someone else’s problem”.

In GitBook, the process is automated. Instead of re-importing an OpenAPI spec every time it’s updated, you can link directly to the source specification and keep everything in sync automatically.

In this guide, we’ll walk through the complete setup: connecting GitBook to GitHub, importing an OpenAPI spec, generating API reference documentation, and customizing the experience for your developers.

What is GitBook’s OpenAPI integration?

GitBook can generate API reference documentation directly from an OpenAPI specification. So rather than manually recreating endpoints, parameters, and schemas inside your docs, you connect GitBook to the source specification and let it handle the rendering.

The specification can be hosted anywhere publicly accessible — including a raw file in GitHub. And once you’ve hooked it up, GitBook keeps the rendered documentation synchronized with the source spec as it changes.

Prerequisites

• A GitHub repo with an OpenAPI spec in YAML format

• A GitBook account (free tier available)

• About 20 minutes

Step 1: Set up your repo and GitBook organization

Fork the GitBook starter repo into your personal GitHub account (not a company org — permissions are simpler that way). The repo has a docs/ directory and an api-specs/ directory with example specs.

Sign up at app.gitbook.com/join and create an organization. The name becomes your default subdomain: your-org.gitbook.io.

Step 2: Connect GitBook to GitHub with Git sync

GitBook’s Git Sync is bidirectional. Commits to your repo update the GitBook editor. Changes in the editor create commits in your repo.

To set it up:

1. Create a new GitBook site and select Sync with Git

2. Authorize GitBook to access your GitHub account

3. Select your repo and branch

4. If you’re using a monorepo, point GitBook at the docs/ subdirectory

5. Set the sync direction to GitHub → GitBook for the initial import

6. Click Sync

For teams that split responsibility between engineering and documentation, this means both groups can work in the tools they’re already comfortable with.

Step 3: Import your OpenAPI specification

1. In GitHub, open your YAML spec and copy the raw file URL

2. In GitBook, go to OpenAPI in the sidebar

3. Click Add Specification, paste the URL, name it, and click Add

GitBook processes the specification and generates a preview of the API reference. From that point onward, the spec remains linked to the original source, so updates can be pulled in automatically without re-importing the file.

Step 4: Add API docs to your pages

There are two ways to do this: a generated API reference for complete endpoint coverage, and embedded endpoint blocks inside guides and tutorials where additional explanation is helpful.

Generate a full API reference section

In the sidebar, click Add New → OpenAPI Reference. GitBook builds a full section with one page per tag in your spec, plus optional model reference pages and a spec download link.

Embed individual endpoints in an existing page

In the GitBook editor, type /, search for OpenAPI, select your spec, and choose which endpoints to insert.

Each embedded block includes the endpoint description, request and response details, example code snippets, and an interactive testing panel. This is useful when you want to explain a workflow in a guide while still showing the underlying API operation alongside it — or offer users a way to test endpoints without leaving your docs.

Step 5: Customize your OpenAPI spec for GitBook

GitBook supports vendor extensions in your YAML that control how the docs render.

Rich descriptions with GitBook blocks

GitBook is built on Markdown, so you can use its block syntax inside spec description fields — steppers, tabs, hints, columns:

info:
  description: |
    {% stepper %}
    {% step %}
    ### Authenticate
    Get your API key from the dashboard.
    {% endstep %}
    {% endstepper %}

info:
  description: |
    {% stepper %}
    {% step %}
    ### Authenticate
    Get your API key from the dashboard.
    {% endstep %}
    {% endstepper %}

info:
  description: |
    {% stepper %}
    {% step %}
    ### Authenticate
    Get your API key from the dashboard.
    {% endstep %}
    {% endstepper %}

info:
  description: |
    {% stepper %}
    {% step %}
    ### Authenticate
    Get your API key from the dashboard.
    {% endstep %}
    {% endstepper %}

Custom page titles and icons

tags:
  - name: payments
    x-displayName: Payments API v3
    x-page-icon: credit-card  # any Font Awesome icon name

tags:
  - name: payments
    x-displayName: Payments API v3
    x-page-icon: credit-card  # any Font Awesome icon name

tags:
  - name: payments
    x-displayName: Payments API v3
    x-page-icon: credit-card  # any Font Awesome icon name

tags:
  - name: payments
    x-displayName: Payments API v3
    x-page-icon: credit-card  # any Font Awesome icon name

Enum descriptions

These show as hover tooltips on enum values:

currency:
  type: string
  enum: [USD, EUR, GBP]
  x-enumDescriptions:
    USD: US Dollar
    EUR: Euro
    GBP

currency:
  type: string
  enum: [USD, EUR, GBP]
  x-enumDescriptions:
    USD: US Dollar
    EUR: Euro
    GBP

currency:
  type: string
  enum: [USD, EUR, GBP]
  x-enumDescriptions:
    USD: US Dollar
    EUR: Euro
    GBP

currency:
  type: string
  enum: [USD, EUR, GBP]
  x-enumDescriptions:
    USD: US Dollar
    EUR: Euro
    GBP

Custom code samples

x-codeSamples:
  - lang: JavaScript
    label: Node
    source: |
      const res = await fetch('/payments', { method: 'POST', ... });
  - lang: Ruby
    source: |
      RestClient.post('/payments', payload)

x-codeSamples:
  - lang: JavaScript
    label: Node
    source: |
      const res = await fetch('/payments', { method: 'POST', ... });
  - lang: Ruby
    source: |
      RestClient.post('/payments', payload)

x-codeSamples:
  - lang: JavaScript
    label: Node
    source: |
      const res = await fetch('/payments', { method: 'POST', ... });
  - lang: Ruby
    source: |
      RestClient.post('/payments', payload)

x-codeSamples:
  - lang: JavaScript
    label: Node
    source: |
      const res = await fetch('/payments', { method: 'POST', ... });
  - lang: Ruby
    source: |
      RestClient.post('/payments', payload)

Stability labels and hiding the Try It panel

x-stability: experimental   # adds a warning label to the endpoint
x-hideTryItPanel: true       # removes the interactive test panel

x-stability: experimental   # adds a warning label to the endpoint
x-hideTryItPanel: true       # removes the interactive test panel

x-stability: experimental   # adds a warning label to the endpoint
x-hideTryItPanel: true       # removes the interactive test panel

x-stability: experimental   # adds a warning label to the endpoint
x-hideTryItPanel: true       # removes the interactive test panel

Push these changes and trigger a manual refresh in GitBook to see them immediately.

Step 6: Publish and configure your site

Click Publish. Under Settings you can change the URL slug, restrict access to authenticated users, set up redirects, and enable the AI assistant.

Step 7: Connect your docs to Cursor, Claude, and other AI tools via MCP

Once your site is published, GitBook automatically generates an MCP (Model Context Protocol) server for it. Your MCP server is live at:

<https://your-site-url/~gitbook/mcp>

<https://your-site-url/~gitbook/mcp>

<https://your-site-url/~gitbook/mcp>

<https://your-site-url/~gitbook/mcp>

Developers can connect tools like Cursor, Claude Desktop, and VS Code directly to your GitBook MCP server at this URL. Once connected, those tools can retrieve information from your published documentation as part of their workflow.

To enable it, make sure Page actions is turned on under Site Customization. Developers can then copy the MCP server URL from the page actions menu on any page and add it to their AI tool of choice.

For API teams, this means developers can ask questions about endpoints, parameters, authentication requirements, or implementation details without having to leave their editor and search through documentation manually.

Without direct access to your documentation, those tools may fall back to older information or incomplete context, which can lead to inaccurate answers about your API.

Does GitBook have an AI assistant for API docs?

Yes. GitBook has a built-in assistant that can answer questions about your docs, including the API reference. Visitors can ask things like “what endpoints are available?” or “how do I create a payment?” and get answers with relevant code snippets pulled from your docs.

You can also embed it as a chat widget in your own product or marketing site.

Frequently asked questions

Can developers use my GitBook docs inside Cursor or Claude? Yes. Every published GitBook site has an MCP server at your-site-url/~gitbook/mcp. Developers add that URL to Cursor, Claude Desktop, or VS Code and their AI tools query your live docs directly instead of relying on training data.

How often does GitBook sync with my OpenAPI spec? Every 6 hours by default. You can force an immediate sync using the Check for Updates button in the OpenAPI section of your dashboard.

Does GitBook support OpenAPI 3.0 and 3.1? Yes, both, in YAML or JSON.

Is GitBook free for API documentation? There’s a free plan for individuals and open source projects. Paid plans add private docs, custom domains, and analytics.

Once everything is connected, your API reference becomes part of the same documentation system as the rest of your content. Engineers can continue maintaining the OpenAPI specification, documentation teams can focus on guides and examples, and GitBook keeps the two synchronized.

If you’d like to see the workflow in action, watch my full workshop for a deeper walkthrough of the setup and customization options.

→ Check out GitBook’s own API documentation

→ Seven principles of great API documentation

→ How to write incredible API documentation