Gestion des opérations API

Apprenez comment marquer une opération 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 supprimées progressivement. 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

Utilisez x-stability pour indiquer qu'un endpoint est instable ou en cours de développement. Cela aide les utilisateurs à éviter les endpoints non prêts pour la production. Valeurs prises en charge : expérimental, alpha, bêta.

openapi.yaml

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

Mettre une opération en dépréciation

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

openapi.yaml

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

Spécifiez éventuellement la fin du support 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 le 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 le placeholder du token

Vous pouvez personnaliser le préfixe d'autorisation (par exemple, Bearer, Token, ou une chaîne personnalisée) et le placeholder du token affiché lors de l'utilisation de schémas de sécurité dans GitBook.

Dans votre spec OpenAPI, sous components.securitySchemes, définissez votre schéma ainsi :

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

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

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

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

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