Skip to main content

​
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

​
Apply schemes globally or per operation

openapi: '3.0.3'
security:
  - bearerAuth: []
paths:
  /users:
    get:
      summary: List users
      # Inherits global bearerAuth security
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

1

Configure CORS properly

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

Provide sandbox environments

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

Document authentication clearly

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

Use realistic examples

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

Hide when inappropriate

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

Build docs developers (and LLMs) love

Get started for freeTalk to us