OpenAPI

Add an OpenAPI spec to a page and let your users test endpoints right on the page with interactive blocks

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.

Add a new pet to the store

Add a new pet to the store

post

/pet

Authorizations

Body

application/jsonapplication/xmlapplication/x-www-form-urlencoded

idinteger · int64

Example: 10

namestringrequired

Example: doggie

categoryobject

statusstring · enum

pet status in the store

Options: available, pending, sold

tagsobject[]

photoUrlsstring[]required

Responses

application/xmlapplication/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v3/pet' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 10,
    "name": "doggie",
    "category": {
      "id": 1,
      "name": "Dogs"
    },
    "status": "available",
    "tags": [
      {
        "id": 1,
        "name": "text"
      }
    ],
    "photoUrls": [
      "text"
    ]
  }'

200

405

200

application/xml

application/json

application/xml

<?xml version="1.0"?>
<pet>
	<id>10</id>
	<name>doggie</name>
	<category>
		<id>1</id>
		<name>Dogs</name>
	</category>
	<status>available</status>
	<tags>
		<tag>
			<id>1</id>
			<name>text</name>
		</tag>
	</tags>
	<photoUrls>
		<photoUrl>text</photoUrl>
	</photoUrls>
</pet>

Successful operation

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.

x-hideTryItPanel

Show or hide the “Test it” button for an OpenAPI block.

Values

true | false

Root level

openapi.yaml

...
x-hideTryItPanel: true
...

Operation level

openapi.yaml

...
paths:
  /user
    get:
      summary: Get the current user
      x-hideTryItPanel: true
...

x-codeSamples

Show or hide code samples for an OpenAPI block Custom code samples are supported, from tools such as Stainless and more by configuring the output from your tool.

Values

true | false | custom

Root level

openapi.yaml

...
x-codeSamples: false
...

Operation level

openapi.yaml

...
paths:
  /user
    get:
      x-codeSamples:
        - lang: 'cURL'
          label: CLI
          source: | 
            curl -L \
            -H 'Authorization: Bearer <token>' \
            'https://api.gitbook.com/v1/user'
...

Create an OpenAPI block using your OpenAPI file

Once you have an OpenAPI compliant representation of your API, you can use it in your documentation.

1. Create a new OpenAPI block using the insert palette.

2. Add your OpenAPI specification, choosing between one of the following options:

   1. Upload your OpenAPI formatted file

   2. 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

1. Choose your API operation

To change the operation that your swagger block is showing, use the "Choose API Operation" option in the block menu

1. 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

1. Using the Block context menu on one of your OpenAPI Blocks, select "Choose OpenAPI Source"

2. 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

1. Using the Block context menu on one of your OpenAPI Blocks, select "Choose OpenAPI Source"

2. 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	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
name	string	Name of the user
age	number	Age of the user

Response

200

{
  "id": 1,
  "name": "John",
  "age": 30
}

400

{
  "error": "Invalid request"
}