Managing API operations

Learn how to mark an OpenAPI API operation as experimental, deprecated or hide it from your documentation.

It’s common to have operations that are not fully stable yet or that need to be phased out. GitBook supports several OpenAPI extensions to help you manage these scenarios.

Marking operation as experimental, alpha, or beta

Use x-stability to communicate that an endpoint is unstable or in progress. It helps users avoid non-production-ready endpoints. Supported values: experimental, alpha, beta.

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      x-stability: experimental

Deprecating an operation

To mark an operation as deprecated, add the deprecated: true attribute.

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      deprecated: true

Optionally specify when support ends by including x-deprecated-sunset

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      deprecated: true
      x-deprecated-sunset: 2030-12-05

Hiding an operation from the API reference

To hide an operation from your API reference, add x-internal: true or x-gitbook-ignore: true attribute.

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      x-internal: true

Hiding a response sample

Add the x-hideSample: true attribute to a response object to exclude it from the response samples section.

openapi.yaml

paths:
  /pet:
    put:
      operationId: updatePet
      responses:
        200:
          x-hideSample: true