Gestion des opérations d’API

Apprenez comment marquer une opération d’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 entièrement 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

Marquer une opération comme obsolète

Pour marquer une opération comme obsolète, ajoutez l’ 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 dans la référence API

Pour masquer une opération de 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