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

Add a new pet to the store.

post

Add a new pet to the store.

Required scopes

This endpoint requires the following scopes:

• : modify pets in your account
• : read your pets

Authorizations

petstore_auth

OAuth2implicitRequired

Authorization URL:

Body

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

idinteger · int64OptionalExample: 10

namestringRequiredExample: doggie

photoUrlsstring[]Required

statusstring · enumOptional

pet status in the store

Possible values:

Responses

200

Successful operation

application/jsonapplication/xml

400

Invalid input

422

Validation exception

default

Unexpected error

post

/pet

HTTPcURLJavaScriptPython

POST /api/v3/pet HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "text"
  ],
  "tags": [
    {
      "id": 1,
      "name": "text"
    }
  ],
  "status": "available"
}

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

{
  "id": 10,
  "name": "doggie",
  "category": {
    "id": 1,
    "name": "Dogs"
  },
  "photoUrls": [
    "text"
  ],
  "tags": [
    {
      "id": 1,
      "name": "text"
    }
  ],
  "status": "available"
}

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
x-hideTryItPanel	true | false	Show or hide the "Test it" button for an OpenAPI block.
x-codeSamples	true | false	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

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

Operation

paths:
  /user
    get:
      summary: Get the current user
      x-hideTryItPanel: true
      x-codeSamples:
       - lang: javascript
          label: JS
          source: console.log('Hello')

Create 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