Extensions reference

The complete reference of OpenAPI extensions supported by GitBook.

We’re currently improving how you build API documentation in GitBook. This page covers features that are being gradually rolled out. If you don’t see them yet, hang tight—they’re on the way!

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.

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

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"

x-parent | parent

Add hierarchy to tags to organize your pages in GitBook.

openapi.yaml

openapi: '3.0'
info: ...
tags:
  - name: organization
  - name: admin
    x-parent: organization
  - name: user
    x-parent: organization

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-codeSamples

Show, hide, or include custom code samples for an OpenAPI block.

Fields

Field Name	Type	Description
lang	string	Code sample language. Value should be one of the following list
label	string	Code sample label, for example Node or Python2.7, optional, lang is used by default
source	string	Code 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'

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.

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

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