# write-openapi

> Claude/Codex skill by [@gitbookio](https://omgskills.com/library/gitbookio/index.md) · 19 stars · Updated 2026-09-24

Author, configure, structure, and troubleshoot OpenAPI/Swagger API reference documentation in GitBook. Use this whenever a task involves a GitBook OpenAPI block or \`{% openapi %}\` block, adding or updating an OpenAPI/Swagger spec in GitBook (by file or URL, via the API, MCP, CLI, or app UI), generating API reference pages from a spec, configuring the interactive "Test it" runner (auth, servers, CORS, proxy), customizing pages with GitBook \`x-\*\` extensions (icons, titles, navigation hierarchy, code samples, enum descriptions), marking operations experimental/deprecated/hidden, or automating spec updates in CI/CD. Trigger even when the user only mentions GitBook plus OpenAPI, puts an \`x-\` extension on a spec destined for GitBook, or asks "why isn't my spec loading" or "why doesn't Test it work", without naming this skill.

## Install

```sh
git clone https://github.com/GitbookIO/gitbook-skills /tmp/gitbook-skills && ln -s /tmp/gitbook-skills/skills/write-openapi ~/.claude/skills/write-openapi
```

## From README

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.

## Links

- HTML page: https://omgskills.com/library/gitbookio/gitbook-skills/skills/write-openapi/
- GitHub: https://github.com/GitbookIO/gitbook-skills
- Author: [@gitbookio](https://omgskills.com/library/gitbookio/index.md)

## More from this repo

- [build-integration](https://omgskills.com/library/gitbookio/gitbook-skills/skills/build-integration/index.md) — Build, develop, and publish GitBook integrations — apps that run inside GitBook to add custom blocks, react to events,...
   - [@gitbookio](https://omgskills.com/library/gitbookio/index.md) · 19 stars
- [cr-review](https://omgskills.com/library/gitbookio/gitbook-skills/skills/cr-review/index.md) — Used to review GitBook change requests from Claude Code by calling the GitBook REST API directly with curl (no CLI) —...
   - [@gitbookio](https://omgskills.com/library/gitbookio/index.md) · 19 stars