Configurer le bouton « Tester »

Vous pouvez configurer le bouton « Test It » et la fenêtre associée dans GitBook à l'aide de plusieurs extensions OpenAPI. Ces extensions peuvent aider à améliorer et à configurer la suite de test pour les utilisateurs.

Masquer le bouton « Test it »

Vous pouvez masquer le bouton « Test it » de vos endpoints en ajoutant le x-hideTryItPanel à un endpoint, ou à la racine de votre spécification OpenAPI.

openapi.yaml

openapi: '3.0'
info: ...
tags: [...]
paths:
  /example:
    get:
      summary: Exemple de résumé
      description: Exemple de description
      operationId: examplePath
      responses: [...]
      parameters: [...]
      x-hideTryItPanel: true

Proxy des requêtes « Test it »

Certaines API bloquent les requêtes du navigateur, souvent à cause du CORS.

Route Tester le trafic via GitBook en ajoutant x-enable-proxy à votre spécification.

Voir Utilisation du proxy OpenAPI pour des exemples.

Activer l'authentification dans la fenêtre de test

Le moteur d'exécution des requêtes peut afficher et appliquer l'authentification uniquement si votre spécification la déclare. Définissez les schémas sous components.securitySchemes, puis associez-les soit globalement via security (s'applique à toutes les opérations) ou par opération (remplace le global).

Déclarez votre schéma d'authentification

Voici des schémas courants. Utilisez des guillemets droits dans 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: 'Lire les éléments'
            write:items: 'Écrire les éléments'

Appliquez les schémas globalement ou par opération

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

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

Contrôlez l'URL du point de terminaison avec `serveurs`

Le moteur d'exécution des requêtes cible les URL que vous définissez dans le serveurs tableau. Déclarez un ou plusieurs serveurs ; vous pouvez également les paramétrer avec des variables.

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

servers:
  - url: https://api.example.com
    description: Production
  - url: https://staging-api.example.com
    description: Préproduction

servers:
  - url: https://{instance}.api.{region}.example.cloud
    variables:
      instance:
        default: acme
        description: Le slug de votre locataire ou de votre instance
      region:
        default: eu
        enum:
          - eu
          - us
          - ap
        description: Déploiement régional

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

Mis à jour il y a 29 jours

Ce contenu vous a-t-il été utile ?