Gestion des opérations API

Découvrez comment marquer une opération API OpenAPI comme expérimentale, obsolète, ou la masquer de votre documentation

Il est courant d’avoir des opérations qui ne sont pas encore totalement stables ou qui doivent être progressivement abandonnées. GitBook prend en charge plusieurs extensions OpenAPI pour vous aider à gérer ces scénarios.

Marquer une opération comme expérimentale, alpha ou bêta

Utiliser x-stability pour indiquer qu’un point de terminaison est instable ou en cours de développement. Cela aide les utilisateurs à éviter les points de terminaison qui ne sont pas prêts pour la production. Valeurs prises en charge : experimental, alpha, beta.

openapi.yaml

paths:
  /pet :
    put :
      operationId: updatePet
      x-stability: experimental

Déprécier une opération

Pour marquer une opération comme dépréciée, ajoutez l’ deprecated: true attribut.

openapi.yaml

paths:
  /pet :
    put :
      operationId: updatePet
      deprecated: true

Indiquez éventuellement quand la prise en charge prend fin en incluant x-deprecated-sunset

openapi.yaml

paths:
  /pet :
    put :
      operationId: updatePet
      deprecated: true
      x-deprecated-sunset: 2030-12-05

Masquer une opération de la référence API

Pour masquer une opération dans votre référence API, ajoutez x-internal: true ou x-gitbook-ignore: true attribut.

openapi.yaml

paths:
  /pet :
    put :
      operationId: updatePet
      x-internal: true

Masquer un exemple de réponse

Ajoutez l’ x-hideSample: true attribut à un objet de réponse pour l’exclure de la section des exemples de réponse.

openapi.yaml

paths:
  /pet :
    put :
      operationId: updatePet
      responses:
        200:
          x-hideSample: true

Personnaliser le préfixe d’autorisation et l’espace réservé du jeton

Vous pouvez personnaliser le préfixe d’autorisation (par exemple, Bearer, Token, ou une chaîne personnalisée) ainsi que l’espace réservé du jeton affiché lors de l’utilisation de schémas de sécurité dans GitBook.

Dans votre spécification OpenAPI, sous components.securitySchemes, définissez votre schéma comme ceci :

openapi.yaml

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      x-gitbook-prefix: Token
      x-gitbook-token-placeholder: YOUR_CUSTOM_TOKEN

Ces extensions :

• x-gitbook-prefix définit le préfixe ajouté avant le jeton.

  • exemple : Authorization: <x-gitbook-prefix> YOUR_API_TOKEN

• x-gitbook-token-placeholder définit la valeur du jeton par défaut.

  • exemple : Authorization: Bearer <x-gitbook-token-placeholder>

x-gitbook-prefix n’est pas pris en charge pour les schémas de sécurité http car ces schémas doivent respecter les définitions d’authentification standard de l’IANA. En savoir plus