extensions-reference.md

description	icon
The complete reference of OpenAPI extensions supported by GitBook.	code

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.

x-page-title | x-displayName

Change the display name of a tag used in the navigation and page title.

{% code title="openapi.yaml" %}

openapi: '3.0'
info: ...
tags:
  - name: users
    x-page-title: Users

{% endcode %}

x-page-description

Add a description to the page.

{% code title="openapi.yaml" %}

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

{% endcode %}

x-page-icon

Add a Font Awesome icon to the page. See available icons here.

{% code title="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"

{% endcode %}

x-parent | parent

Add hierarchy to tags to organize your pages in GitBook.

{% code title="openapi.yaml" %}

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

{% endcode %}

x-hideTryItPanel

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

{% code title="openapi.yaml" %}

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true

{% endcode %}

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

{% code title="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'

{% endcode %}

x-enumDescriptions

Add an individual description for each of the enum values in your schema.

{% code title="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.

{% endcode %}

x-internal | x-gitbook-ignore

Hide an endpoint from your API reference.

{% code title="openapi.yaml" %}

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-internal: true

{% endcode %}

x-stability

Mark endpoints that are unstable or in progress.

Supported values: experimental, alpha, beta.

{% code title="openapi.yaml" %}

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      x-stability: experimental

{% endcode %}

deprecated

Mark whether an endpoint is deprecated or not. Deprecated endpoints will give deprecation warnings in your published site.

{% code title="openapi.yaml" %}

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Example summary
      description: Example description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      deprecated: true

{% endcode %}

x-deprecated-sunset

Add a sunset date to a deprecated operation.

Supported values: ISO 8601 format (YYYY-MM-DD)

{% code title="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

{% endcode %}