Configuring the “Test it” button

You can configure the "Test It" button and accompanying window in GitBook using several OpenAPI extensions. These extensions can help improve and configure the testing suite for users.

Hiding the “Test it” button

You can hide the “Test it” button from your endpoints by adding the x-hideTryItPanel to an endpoint, or at the root of your OpenAPI spec.

openapi.yaml

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

Proxy “Test it” requests

Some APIs block browser requests, often because of CORS.

Route Test it traffic through GitBook by adding x-enable-proxy to your spec.

See Using OpenAPI proxy for examples.

Enable authentication in the testing window

The request runner can only present and apply auth if your spec declares it. Define schemes under components.securitySchemes, then attach them either globally via security (applies to all operations) or per-operation (overrides global).

Declare your auth scheme

Below are common patterns. Use straight quotes in YAML.

openapi: '3.0.3'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

openapi: '3.0.3'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://auth.example.com/oauth/authorize'
          tokenUrl: 'https://auth.example.com/oauth/token'
          scopes:
            read:items: 'Read items'
            write:items: 'Write items'

Apply schemes globally or per operation

openapi: '3.0.3'
security:
  - bearerAuth: []
paths: ...

Control the endpoint URL with `servers`

The request runner targets the URL(s) you define in the servers array. Declare one or more servers; you can also parameterize them with variables.

openapi: '3.0.3'
servers:
  - url: https://instance.api.region.example.cloud

servers:
  - url: https://{instance}.api.{region}.example.cloud
    variables:
      instance:
        default: acme
        description: Your tenant or instance slug
      region:
        default: eu
        enum:
          - eu
          - us
          - ap
        description: Regional deployment

Last updated 7 days ago

Was this helpful?

Good morning

hashtagHiding the “Test it” button

hashtagProxy “Test it” requests

hashtagEnable authentication in the testing window

hashtagDeclare your auth scheme

hashtagApply schemes globally or per operation

hashtagControl the endpoint URL with servers