Extensions reference | GitBook Documentation
New: The GitBook MCP server is here.
Connect your AI agent
Ctrlk
ProductPricingBook a demoLog inSign up
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Extensions reference

The complete reference of OpenAPI extensions supported by GitBook

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"
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
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-expandAllResponses

Expand all response sections by default, instead of showing only one at a time.

Add it at the root to apply it to every operation. Add it on an operation to apply it to that one endpoint.

x-expandAllModelSections

Expand all model/schema sections by default, showing nested object properties without requiring user interaction.

Add it at the root to apply it to every operation. Add it on an operation to apply it to that one endpoint.

x-enable-proxy

Route “Test it” requests through GitBook’s OpenAPI proxy.

Add it at the root to apply it to every operation. Add it on an operation to apply it to that one endpoint. Operations override the root value.

Read more in Using OpenAPI proxy.

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

x-enumDescriptions

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

x-internal | x-gitbook-ignore

Hide an endpoint from your API reference.

x-stability

Mark endpoints that are unstable or in progress.

Supported values: experimental, alpha, beta.

deprecated

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

x-deprecated-sunset

Add a sunset date to a deprecated operation.

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

Last updated

Was this helpful?