Gérer les opérations API

Découvrez 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 totalement stables ou qui doivent être progressivement retirées. GitBook prend en charge plusieurs extensions OpenAPI pour vous aider à gérer ces situations.

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

Utilisez 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 : expérimental, alpha, bêta.

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’ deprecated: true attribut.

openapi.yaml

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

Vous pouvez éventuellement préciser 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 de l’API

Pour masquer une opération de votre référence de l’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, Jeton, 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: Jeton
      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 par défaut du jeton.

  • 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 respecter les définitions d’authentification standard de l’IANA. En savoir plus