GitBook OpenAPI

GitBook turns an OpenAPI document into interactive, testable API reference blocks. You give it a spec (as JSON or YAML), and it renders endpoints, parameters, schemas, auth, and an in-page request runner. Most of the customization happens inside the spec itself through x-* extensions, not in the GitBook UI, so the bulk of any task here is editing OpenAPI YAML correctly.

This skill covers the full surface: getting a spec into GitBook, generating reference pages, structuring navigation, making the "Test it" runner work, controlling how operations and schemas display, and automating updates from CI/CD.

Key facts to know first

These shape almost every decision, so internalize them before editing anything.

• Supported versions. GitBook accepts Swagger 2.0 and OpenAPI 3.0 specs. Some features need newer versions: webhooks require OpenAPI 3.1, and the official parent tag property requires OpenAPI 3.2+ (use x-parent on 3.0.x and 3.1.x). Always check the spec's openapi:/swagger: version before reaching for a version-gated feature.
• The "Test it" runner is powered by Scalar. It runs requests from the reader's browser unless you route them through GitBook's proxy.
• Three ways to add a spec: upload a file, point at a hosted URL, or publish with the GitBook CLI. The source type changes how updates work (see below).
• URL specs auto-refresh every 6 hours. File specs only change when re-uploaded or re-published.
• x-* extensions are namespaced and safe to keep in a shared spec. Tools that do not understand a given extension ignore it, so a spec instrumented for GitBook still validates and works elsewhere.

What are you trying to do?

Match the task to the right section. For the deeper reference material, two files live alongside this one: