write-openapi

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.

How you can talk to GitBook

Most of this skill — editing the OpenAPI YAML/JSON itself — is transport-agnostic. But getting a spec into GitBook, or generating/inserting reference pages, does touch GitBook, and there's more than one way to do that: GitBook's MCP server and the REST API. Check what's actually available in the current session and prefer MCP first: if GitBook MCP tools are already connected, use them for anything they cover (publishing/updating a spec, generating reference pages) instead of making direct API calls. Don't run a detection script for this — you already know your own available tools/MCP connections; just use that awareness.

The steps below are described as outcomes ("add the spec", "generate the reference pages") rather than tied to one transport, so they apply whichever you use. If GitBook MCP tools are connected, call those directly — their own schemas describe their parameters. If you're on the REST API path instead, the exact endpoints and request bodies are in "Add or update a specification" below.

• GitBook MCP — a full read/write surface over the same capabilities described below, not a narrower view. If it isn't connected yet and the task is substantial enough to benefit (publishing a new spec, generating a full reference — not a one-off tweak), offer to set it up: claude mcp add --transport http gitbook-mcp https://mcp.gitbook.com/mcp (then /mcp to complete OAuth sign-in — or append --header "Authorization: Bearer $GITBOOK_TOKEN" to skip the browser flow). Codex equivalent: codex mcp add gitbook-mcp --url https://mcp.gitbook.com/mcp. Note: this is a different server from GitBook's separate, read-only "published docs" MCP, which only exposes already-published content.
• REST API (https://api.gitbook.com/v1) — the fallback when MCP isn't connected, or for anything MCP doesn't cover. Needs GITBOOK_TOKEN as a bearer header on every request.

The same personal access token (from https://app.gitbook.com/account/developer) works as the bearer token for both. MCP additionally supports OAuth as a friendlier alternative to pasting a token.

If you end up needing a token (REST API path, or MCP without OAuth), check for it at the start of the session: