OpenAPI
Manually writing REST API documentation can be time-consuming. GitBook streamlines this task by allowing you to import OpenAPI documents, which detail your API’s structure and functionality. The OpenAPI Specification (OAS) is a framework that developers use to document REST APIs. Written in JSON or YAML, it outlines all your endpoints, parameters, schemas, and authentication schemes. Once imported into GitBook, these documents are transformed into interactive and testable API blocks that visually represent your API methods—whether the specification is provided as a file or loaded from a URL.Supported versions
GitBook supports the following OpenAPI specifications:Interactive API blocks
OpenAPI blocks in GitBook display your API endpoints with complete documentation including:- Request parameters and body schemas
- Response schemas and examples
- Authentication requirements
- Interactive testing capability
All OpenAPI blocks are automatically generated from your specification and stay in sync when you update the spec.
Test it functionality
GitBook’s OpenAPI block supports a “Test it” functionality, which allows your users to test your API methods with data and parameters filled in from the editor. Powered by Scalar, you won’t need to leave the docs in order to see your API methods in action. Your users can:- Fill in authentication credentials
- Customize request parameters
- Execute live API calls
- View real responses
CORS requirements for URL-based specs
If you added your specification via URL, your API must allow cross-origin GET requests from your docs site. In your API’s CORS settings, allow the exact origin where your docs are hosted:https://your-site.gitbook.iohttps://docs.example.com
Next steps
Add a specification
Learn how to upload or link your OpenAPI spec
Insert in docs
Generate pages and blocks from your specification