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

Enable authentication in the testing window

components.securitySchemessecurity

Declare your auth scheme

Below are common patterns. Use straight quotes in YAML.

HTTP Bearer (e.g., JWT)

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

API Key in header

openapi: '3.0.3'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

OAuth2 (authorizationCode)

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

Gloabl

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

Per-operation

paths:
  /reports:
    get:
      summary: Get reports
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: OK

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.

Single server

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

Multiple servers

servers:
  - url: https://api.example.com
    description: Production
  - url: https://staging-api.example.com
    description: Staging

Server variables

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

Per-operation servers

paths:
  /reports:
    get:
      summary: Get reports
      servers:
        - url: https://reports.api.example.com
      responses:
        '200':
          description: OK