APIs are increasingly important to product teams. But an API isn’t useful without great docs — which is why choosing the best API documentation tool is vital.

We’ve been focused on improving the way that you create and maintain API docs in GitBook. And with our latest release, we’ve made the process much more streamlined and built for the future — using

A quick TL;DR

• Generate API reference docs in seconds based on your OpenAPI specifications — with page structure and content auto-formatted so your docs look great by default

• You can still insert individual endpoints into any page manually too — great for writing guides

• GitBook automatically checks for OpenAPI spec updates every six hours and reflects those changes in your docs instantly

• This is our first use of computed content — a powerful new way to create and update content in GitBook

Overcoming API documentation challenges

According to the recent State of Docs Report, the two things that teams want most when documenting APIs are both related to automation: automatic doc creation when uploading a spec, and automatic updates when that spec changes. The next most important thing was the option to run endpoint tests right on the page.

GitBook already offers ‘Test it’ functionality for API docs. And our latest project focused on the other two — auto docs generation and automatic updates.

Generate API docs in seconds

Firstly, we’ve redesigned the way that you generate API documentation from an OpenAPI specification in GitBook.

Before this update, you created API docs at a space level — but the process was more granular. You had to create pages, add OpenAPI blocks, choose your spec, then choose which endpoints you wanted on each page individually. If you wanted to generate a full API reference in one go, it was a time-consuming process.

So we’ve simplified things. You can now add and manage your API specifications at an organization level, and use them to generate API reference docs in seconds.

You add your API specifications in the OpenAPI screen — accessible through the sidebar. Here you can upload your spec file, add it from a URL, or use the GitBook CLI. And it’s easy to add more specifications, copy, or download the raw spec all in one place.

Then, when you’re ready to create your documentation, you have two choices.

To create full API reference docs, simply click Add new… at the bottom of your space’s table of contents and choose OpenAPI Reference. You’ll be prompted to choose your spec, decide whether you want to include a model reference page, and then simply click a button.

GitBook instantly generates pages from your specification and adds the relevant endpoints to them. And they’ll automatically look great. The new pages pull all the data they need directly from your specification, page titles and descriptions, extra context around endpoints, and more. Effectively, GitBook uses your spec file to write the docs for you.

And of course, you can still use the old system — inserting OpenAPI blocks to individual pages and choosing the endpoints you want to add to each one. This is great if you want to write tutorials or guides that include specific endpoints within a larger piece of content.

API docs that are always up to date

Best of all, if you add your specification to GitBook using a URL, the spec file will automatically update every six hours — or you can update it manually, if you want.

Choose your specification in the OpenAPI section in GitBook and you’ll see when it was last updated. Just updated your specification and want to push the changes to your docs immediately? Hit Check for updates.

When the specification file is updated — automatically or manually — GitBook pushes any changes to your docs instantly. No need to open a change request or re-upload your specification. Your docs will get the latest information without you lifting a finger, so the only thing you need to worry about is updating your spec.

Want to see how docs look when created using this new process? Check out our own API reference to see for yourself.

Our first use-case for computed content

This new OpenAPI system in GitBook is the first feature to use a new kind of process that we internally call computed content. Essentially, the idea of computed content is taking existing information — in this case an API specification — and using it to automatically create documentation in seconds.

Part of the power of computed content is that it automatically updates when the source content is changed.

This week, we’ll talk more about how we built this system and how we plan to expand on it in future. The next big computed content feature we’ve been working on is all about internationalization and auto-translated docs that update when you edit your source docs. We’ll talk about this in more detail soon — and also dive into the technical side of how we built the foundation for these features.

Computed content also plays an important role in our vision for the future of documentation — where docs adapt to the needs of individual users. We’re excited to be rolling out the first step of that vision, and we can’t wait to show you what else we’re working on.

For now, we hope you like these new API improvements. As always, if you have any ideas or feedback you think could help us make this or any other GitBook feature better, please join our GitHub community and share it with the team — we’re always listening!

See you on Wednesday for more.

→ Read the OpenAPI docs

→ Get started with GitBook for free

→ Read the full State of Docs Report 2025