Gestion des opérations API

Apprenez 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 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 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 obsolète, ajoutez l'attribut deprecated: true:

openapi.yaml

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

Vous pouvez éventuellement spécifier la date de fin de support en ajoutant 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 de votre référence API, ajoutez l'attribut x-internal: true ou x-gitbook-ignore: true.

openapi.yaml

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