OpenAPI methods
Add an OpenAPI spec to a page.
You can sync with an OpenAPI or Swagger file or URL to include auto-generated methods in your documentation.
Test it (powered by Scalar)
GitBook's OpenAPI block also supports a "try 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. See and example of this below.
Example of an OpenAPI block
Manually writing documentation for your REST API can be time-consuming. To help, GitBook supports OpenAPI document imports, which describe your API, and provides API blocks. These will automatically represent your API methods based on the specification you provide — either as a file or as a URL for GitBook to load.
GitBook supports Swagger 2.0 or OpenAPI 3.0 compliant files.
Options
GitBook supports extra options you can define in your OpenAPI specification to alter they way your API methods display in your published documentation.
Property | Values | Description |
---|---|---|
|
| Show or hide the "Test it" button for an OpenAPI block. |
|
| Show or hide code samples for an OpenAPI block. |
Both properties can be set on either the root level or on a per-operation basis.
Root
Operation
Create OpenAPI block using your OpenAPI file
Once you have an OpenAPI compliant representation of your API, you can use it in your documentation.
Create a new OpenAPI block using the insert palette.
Add your OpenAPI specification, choosing between one of the following options:
Upload your OpenAPI formatted file
Provide a URL to your publicly available OpenAPI file.
If you’re providing a URL, make sure that the file is available on the open internet, and that it’s not behind any kind of password protection.
If you’re just experimenting, you can use one of the default Swagger files:
https://petstore.swagger.io/v2/swagger.json
Choose your API operation
To change the operation that your swagger block is showing, use the "Choose API Operation" option in the block menu
Show more than one operation
Your API is likely to have more than one operation that you'll want to document. Each OpenAPI block shows one API operation. In order to show multiple API operations, you can create an extra OpenAPI block per operation, backed by the same OpenAPI specification file.
Update your specification
From time to time you might need to update or modify your API specification. In GitBook, you can replace the specification underlying your OpenAPI blocks, and have the update be reflected across all your documentation.
Replacing a specification in a file
Using the Block context menu on one of your OpenAPI Blocks, select "Choose OpenAPI Source"
On your OpenAPI file in the file list, click "Replace"
Once the OpenAPI Source has been replaced, each OpenAPI block that references your file will be updated based on your new specification.
Replacing a specification from a link
Using the Block context menu on one of your OpenAPI Blocks, select "Choose OpenAPI Source"
Provide a new URL in the input box, and save
Once the OpenAPI Source has been replaced, each OpenAPI block that references your file will be updated based on your new specification.
API method block (deprecated)
Editable API method blocks are now deprecated
In light of our updated OpenAPI method block, we’ve decided to deprecate the API method block. Read our recent announcement to find out more about the reasons behind this change.
On Monday 4 March 2024, we automatically transitioned all pre-existing API method blocks to regular blocks in the format you can see below. Read our announcement to find out more.
You can still create editable API references from the Quickstart section of the Insert menu. Hit / on your keyboard and select API Reference. GitBook will create an editable section that looks like this:
Create a new user
POST
/users
<Description of the endpoint>
Headers
Name | Value |
---|---|
Content-Type |
|
Authorization |
|
Body
Name | Type | Description |
---|---|---|
| string | Name of the user |
| number | Age of the user |
Response
Last updated