A faster way to build API documentation with OpenAPI and AI

The original GitBook OpenAPI workshop showed how to go from a specification file to a published, auto-updating documentation site in about 20 minutes.

That’s already a fast workflow. But many of the tasks that used to take the longest are now areas where AI can help.

Generating an OpenAPI specification, improving descriptions and examples, writing ‘getting started’ content, and answering developer questions are all tasks that can be accelerated with the right tools.

The result isn’t fully automated documentation, because the human element is still really important to accurate, high-quality docs. However, it does mean you’ll spend less time on repetitive setup work and more time reviewing, refining, and improving the experience for your users.

In this article, we’ll explore what that workflow looks like today.

Where AI can help throughout the workflow

There are four parts of the API documentation workflow where AI can make a meaningful difference:

1. Generating an OpenAPI specification – if you don’t have one yet, or your existing specification is incomplete

2. Creating supporting documentation – using GitBook Agent to draft and improve guides, overviews, and explanations

3. Helping developers find answers – using GitBook Assistant to answer questions from your published docs

4. Making documentation available to AI tools – using GitBook’s MCP server to make your docs accessible from tools like Cursor, Claude Desktop, and VS Code

Each removes some manual work from the documentation process. Together, they change where teams spend their time.

1. Generate your OpenAPI specification with Claude or ChatGPT

Many teams either don’t have an OpenAPI specification yet or have one that’s missing descriptions, examples, and useful metadata. Creating and maintaining that information manually can take time, which is why this is one of the areas where LLMs can be particularly useful.

Open Claude or ChatGPT and provide the details of your API. You don’t need an elaborate prompt. Something like this is often enough:

I have a payments API. It has two endpoints: POST /payments to create a payment (fields: amount, currency, customer_id) and GET /payments/{id} to retrieve one. Generate a complete OpenAPI 3.1 specification in YAML with descriptions, examples, and enum values for currency (USD, EUR, GBP).

You’ll get a working specification back in seconds. From there, you can ask the model to add GitBook-specific extensions in the same conversation:

Also add x-displayName and x-page-icon for each tag, x-enumDescriptions for the currency field, and mark the refunds endpoint as x-stability: experimental.

Without AI, you’d need to look up the extensions and update the YAML manually. With AI, much of that work can be generated alongside the rest of the specification.

Once you have the specification, commit it to GitHub. You can then connect it to GitBook, which will automatically generate a complete API reference from your spec file, giving you a single source of truth for your API. And if you update the API specification later, your API reference in GitBook will update automatically too.

2. Use GitBook Agent to draft supporting documentation

Once your repository is connected and your API reference is generated, you still need the content that helps developers succeed — getting started guides, authentication pages, tutorials, and product context.

GitBook Agent is built into the editor and can propose changes directly through a change request.

Try prompts such as:

• “Write a getting started guide for a developer who has never used this API before”

• “Add a page explaining authentication and how to get an API key”

• “Check grammar and tone consistency across all pages”

• “Rewrite the payments overview page for a less technical audience”

Rather than starting from a blank page, you’re reviewing and refining a draft that already understands the context of your documentation.

GitBook Agent uses the context of the rest of your documentation to create relevant content in the change request. And while you remain in control of what gets merged, the first draft can now arrive much faster than it would before.

3. Let GitBook Assistant answer common questions

Once your documentation is published, GitBook Assistant becomes available to your visitors. It can search across your documentation — including generated API references — and answer questions using the content you’ve already published.

For example, a developer might ask:

“How do I create a payment in Python?”

The Assistant can locate the relevant endpoint, surface the Python example from your documentation, and provide a direct answer including a code sample without requiring the user to navigate multiple pages.

You can also embed the Assistant inside your product so customers can ask questions without leaving your application.

To enable it, go to Site Settings → Search and turn on the Assistant. You can also add suggested questions to help first-time visitors understand what they can ask.

4. Make your documentation available through MCP

Most OpenAPI tutorials stop once the documentation is published. But today, static documentation is only a small part of the workflow.

Many developers now spend a significant portion of their time inside AI-powered tools such as Cursor, Claude Desktop, and VS Code. Making your documentation available directly inside those environments can be just as important as publishing it on the web.

When GitBook publishes your site, it automatically generates an MCP (Model Context Protocol) server available at:

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

If your users work in Cursor, Claude Desktop, or VS Code, they can add this URL to their AI tool settings and query your documentation directly while they work.

Instead of relying on potentially outdated training data, AI tools can retrieve answers from your current documentation, including the latest endpoints, examples, and field names.

The MCP is generated from your docs automatically ready for any reader to use. You can make the MCP server more discoverable by enabling Page actions under Site Customization. GitBook will then surface the MCP URL directly in the page actions menu.

The setup takes less than a minute, but it can significantly increase the likelihood that developers receive accurate answers based on your latest documentation.

What the workflow looks like today

The parts that don’t change are connecting your repository, publishing your site, and configuring the experience. Those are still manual steps, but they’re also some of the quickest parts of the process. And we’re already hard at work on making these processes accessible to AI tools as well, so the likes of Claude Code and Codex will be able to handle the entire process.

What you still need to do yourself

AI can remove a lot of repetitive work, but it doesn’t remove the need for judgment.

You should still:

• Review generated specifications for accuracy

• Verify examples and field names

• Review GitBook Agent changes before merging

• Structure content in a way that helps both humans and AI systems find the right information

The common thread across all of these tools is that they help you start faster, not think less.

AI can accelerate documentation work, but accuracy and clarity still depend on the people maintaining it.

How quickly can you get from zero to published docs?

Starting with no specification and no GitBook account? Here’s the steps to complete and how long they take:

• Generate an OpenAPI specification with AI: 2–3 minutes

• Create a GitBook account and connect GitHub: 3–4 minutes

• Import the specification and publish: 2 minutes

• Draft a getting started guide with GitBook Agent: 2 minutes to prompt, a few minutes to review

• Make MCP access more discoverable: less than 1 minute

In practice, it only takes around 15 minutes to publish an API reference, create supporting documentation, enable AI-powered assistance, and make your documentation available through MCP using GitBook.

The original workshop showed how quickly a team could build API documentation manually. Today, many of the supporting tasks around that workflow can be accelerated as well, which means you can spend less time setting things up and more time improving the experience for your users.

This article is based our recent GitBook OpenAPI workshop. If you’d like to understand the full workflow in more detail, including the manual setup process, the original workshop is a great place to start.

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

→ 5 ways to improve your technical writer skills for 2026

→ Seven principles of great API documentation