Test it button

You can configure the “Test it” button and accompanying window in GitBook using several OpenAPI extensions. These extensions help improve and configure the testing suite for users. The interactive test functionality is powered by Scalar and allows users to execute live API requests directly from your documentation.

Hiding the test it button

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

openapi.yaml

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

For all endpoints (at root level):

openapi.yaml

openapi: '3.0'
info: ...
x-hideTryItPanel: true
paths:
  # All operations will have "Test it" hidden

Hiding the test functionality is useful for documentation-only endpoints, webhooks, or operations that require complex setup that can’t be easily replicated in the browser.

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:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

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:
  /users:
    get:
      summary: List users
      # Inherits global bearerAuth security

paths:
  /reports:
    get:
      summary: Get reports
      security:
        - apiKeyAuth: []
      responses:
        '200':
          description: OK
  /public/status:
    get:
      summary: Public status endpoint
      security: []
      # Empty array means no authentication required

When you define security schemes, GitBook automatically adds an authentication input field to the “Test it” panel, allowing users to provide their credentials.

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.yaml

openapi: '3.0.3'
servers:
  - url: https://api.example.com

Multiple servers

openapi.yaml

servers:
  - url: https://api.example.com
    description: Production
  - url: https://staging-api.example.com
    description: Staging
  - url: http://localhost:3000
    description: Local development

Users can select which server to target from a dropdown in the test panel.

Server variables

For dynamic server URLs, use variables that users can customize:

openapi.yaml

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

This allows users to input their specific instance and region before testing.

Per-operation servers

You can override the global servers array for specific operations:

openapi.yaml

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

Ensure your API servers have proper CORS headers configured to allow requests from your documentation domain. Otherwise, browser-based testing will fail.

Complete example

Here’s a complete example showing authentication, servers, and test configuration:

openapi.yaml

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0

servers:
  - url: https://api.example.com
    description: Production
  - url: https://sandbox.example.com
    description: Sandbox

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token from /auth/login

security:
  - bearerAuth: []

paths:
  /users:
    get:
      summary: List all users
      description: Returns a paginated list of users
      responses:
        '200':
          description: Success
  
  /public/health:
    get:
      summary: Health check
      description: Public endpoint to check API status
      security: []
      # No authentication required
      responses:
        '200':
          description: API is healthy
  
  /admin/logs:
    get:
      summary: View admin logs
      description: Internal endpoint
      x-hideTryItPanel: true
      # Test button hidden for sensitive endpoint
      responses:
        '200':
          description: Log entries

Best practices

Configure CORS properly

Ensure your API allows cross-origin requests from your documentation domain. Test the “Test it” functionality thoroughly.

Provide sandbox environments

Include a sandbox or staging server in your servers array so users can test without affecting production data.

Document authentication clearly

In your security scheme descriptions, explain how users can obtain valid credentials for testing.

Use realistic examples

Provide example values in your spec so the test panel is pre-populated with sensible defaults.

Hide when inappropriate

Use x-hideTryItPanel for operations that can’t be easily tested in a browser, like file uploads or webhooks.

OpenAPI

Guides

Reference

Test it button

Test it button

Hiding the test it button

Enable authentication in the testing window

Declare your auth scheme

Apply schemes globally or per operation

Control the endpoint URL with servers

Single server

Multiple servers

Server variables

Per-operation servers

Complete example

Best practices

​Test it button

​Hiding the test it button

​Enable authentication in the testing window

​Declare your auth scheme

​Apply schemes globally or per operation

​Control the endpoint URL with servers

​Single server

​Multiple servers

​Server variables

​Per-operation servers

​Complete example

​Best practices

Test it button

Hiding the test it button

Enable authentication in the testing window

Declare your auth scheme

Apply schemes globally or per operation

Control the endpoint URL with servers

Single server

Multiple servers

Server variables

Per-operation servers

Complete example

Best practices