Skip to main content

​
Extensions reference

You can enhance your OpenAPI specification using extensions—custom fields that start with the x- prefix. These extensions let you add extra information and tailor your API documentation to suit different needs. GitBook allows you to adjust how your API looks and works on your published site through a range of different extensions you can add to your OpenAPI spec. Head to our guides section to learn more about using OpenAPI extensions to configure your documentation.

​
Page customization

​
x-page-title | x-displayName

Change the display name of a tag used in the navigation and page title.
openapi.yaml
openapi: '3.0'
info: ...
tags:
  - name: users
    x-page-title: Users

​
x-page-description

Add a description to the page.
openapi.yaml
openapi: '3.0'
info: ...
tags:
  - name: "users"
    x-page-title: "Users"
    x-page-description: "Manage user accounts and profiles."

​
x-page-icon

Add a Font Awesome icon to the page. See available icons at fontawesome.com/search.
openapi.yaml
openapi: '3.0'
info: ...
tags:
  - name: "users"
    x-page-title: "Users"
    x-page-description: "Manage user accounts and profiles."
    x-page-icon: "user"

​
parent | x-parent

Add hierarchy to tags to organize your pages in GitBook.
parent is the official property name in OpenAPI 3.2+. If using OpenAPI versions prior to 3.2 (3.0.x, 3.1.x), use x-parent instead.
openapi.yaml
openapi: '3.2'
info: ...
tags:
  - name: organization
  - name: admin
    parent: organization
  - name: user
    parent: organization

​
Operation visibility

​
x-hideTryItPanel

Show or hide the “Test it” button for an OpenAPI block.
openapi.yaml
openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true

​
x-internal | x-gitbook-ignore

Hide an endpoint from your API reference.
openapi.yaml
openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-internal: true

​
Code samples

​
x-codeSamples

Show, hide, or include custom code samples for an OpenAPI block. Fields:
Field NameTypeDescription
langstringCode sample language. Value should be one of the linguist popular languages
labelstringCode sample label, for example Node or Python2.7, optional, lang is used by default
sourcestringCode sample source code
openapi.yaml
openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-codeSamples:
        - lang: 'cURL'
          label: 'CLI'
          source: |
            curl -L \
            -H 'Authorization: Bearer <token>' \
            'https://api.gitbook.com/v1/user'

​
Enum descriptions

​
x-enumDescriptions

Add an individual description for each of the enum values in your schema.
openapi.yaml
openapi: '3.0'
info: ...
components:
  schemas:
    project_status:
      type: string
      enum:
        - LIVE
        - PENDING
        - REJECTED
      x-enumDescriptions:
        LIVE: The project is live.
        PENDING: The project is pending approval.
        REJECTED: The project was rejected.

​
Operation lifecycle

​
x-stability

Mark endpoints that are unstable or in progress. Supported values: experimental, alpha, beta
openapi.yaml
openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      x-stability: experimental

​
deprecated

Mark whether an endpoint is deprecated or not. Deprecated endpoints will give deprecation warnings in your published site.
openapi.yaml
openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true

​
x-deprecated-sunset

Add a sunset date to a deprecated operation. Supported values: ISO 8601 format (YYYY-MM-DD)
openapi.yaml
openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true
      x-deprecated-sunset: 2030-12-05

​
Response customization

​
x-hideSample

Hide response samples for specific response codes.
openapi.yaml
paths:
  /pet:
    put:
      operationId: updatePet
      responses:
        200:
          x-hideSample: true
          description: Successful operation

​
Authentication customization

​
x-gitbook-prefix

Customize the authorization prefix shown in security schemes.
x-gitbook-prefix is not supported for http security schemes because these schemes must follow standard IANA authentication definitions. Learn more
openapi.yaml
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      x-gitbook-prefix: Token
      x-gitbook-token-placeholder: YOUR_CUSTOM_TOKEN
Example output: 
Authorization: Token YOUR_CUSTOM_TOKEN

​
x-gitbook-token-placeholder

Set the default token placeholder value shown in examples.
openapi.yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-gitbook-token-placeholder: your_jwt_token_here
Example output: 
Authorization: Bearer your_jwt_token_here

​
Extension compatibility matrix

ExtensionApplies ToOpenAPI VersionsDescription
x-page-title / x-displayNameTags2.0, 3.0, 3.1, 3.2Custom page title
x-page-descriptionTags2.0, 3.0, 3.1, 3.2Page subtitle
x-page-iconTags2.0, 3.0, 3.1, 3.2Font Awesome icon
parent / x-parentTags3.2 / 2.0, 3.0, 3.1Hierarchical navigation
x-hideTryItPanelOperations, Root2.0, 3.0, 3.1, 3.2Hide test functionality
x-codeSamplesOperations2.0, 3.0, 3.1, 3.2Custom code examples
x-enumDescriptionsSchemas2.0, 3.0, 3.1, 3.2Enum value descriptions
x-internal / x-gitbook-ignoreOperations2.0, 3.0, 3.1, 3.2Hide from docs
x-stabilityOperations2.0, 3.0, 3.1, 3.2Lifecycle status
deprecatedOperations2.0, 3.0, 3.1, 3.2Deprecation flag
x-deprecated-sunsetOperations2.0, 3.0, 3.1, 3.2Deprecation date
x-hideSampleResponses2.0, 3.0, 3.1, 3.2Hide response samples
x-gitbook-prefixSecurity Schemes2.0, 3.0, 3.1, 3.2Auth prefix
x-gitbook-token-placeholderSecurity Schemes2.0, 3.0, 3.1, 3.2Token placeholder

​
Further reading

Structuring API reference

Learn how to organize your API documentation

Custom code samples

Add language-specific examples

Managing operations

Control operation visibility and lifecycle

Test it button

Configure interactive testing

Build docs developers (and LLMs) love

Get started for freeTalk to us