OpenAPI
Traduisez les champs explicatifs des fichiers YAML OpenAPI 3.x tout en préservant les chemins, les identifiants d’opération et les références.
Un document OpenAPI associe un contrat d’API lisible par machine à des explications destinées aux personnes qui l’utilisent. Le gestionnaire de fichiers yaml-openapi sélectionne les champs title, description et summary selon leur emplacement dans le document YAML OpenAPI 3.x. Les chemins, les identifiants d’opération et les références restent inchangés.
Préservez la stabilité du contrat d’API #
Dans cet exemple, l’opération conserve son identité, tandis que son explication peut être traduite dans une autre langue :
openapi: 3.0.3
info:
title: Order service
version: 1.0.0
paths:
/orders:
get:
operationId: listOrders
summary: List your orders
responses:
"200":
description: Orders retrievedLe gestionnaire sélectionne le titre, le résumé et la description de la réponse. /orders, listOrders et 1.0.0 restent inchangés. La sélection couvre également les champs d’information, les descriptions des étiquettes et de la documentation externe, les descriptions des chemins, ainsi que les champs descriptifs des conteneurs de schémas et d’opérations reconnus.
Examinez les exemples et les valeurs par défaut de type objet dans ces conteneurs. Une propriété imbriquée nommée title, description ou summary peut également être sélectionnée, même lorsqu’elle représente des données d’exemple de charge utile. Les autres valeurs de schéma, comme les chaînes d’énumération ordinaires et les valeurs $ref, restent inchangées.
L’analyseur exige une structure YAML de type dictionnaire avec une version openapi commençant par 3.. Il rejette Swagger 2.x, les documents sans version et les autres versions. Un fichier OpenAPI au format JSON n’est pas sélectionné au seul motif qu’OpenAPI autorise JSON : ce gestionnaire prend en charge le format YAML.
Reconstruction et réutilisation #
La source actuelle définit l’arborescence de la spécification. Les formulations existantes sont mises en correspondance selon l’identité et l’occurrence des champs descriptifs ; l’identité de l’opération contribue également à cet alignement. Les descriptions modifiées dans la source nécessitent une nouvelle traduction, tandis que les champs correspondants restés inchangés peuvent reprendre la formulation cible existante.
Le sérialiseur YAML reconstruit le document et peut en normaliser la mise en forme. Veillez à garder les versions précédentes des spécifications source et cible alignées, et examinez les déplacements de champs ou les descriptions répétées qui influent sur la réutilisation.
Sélectionnez le gestionnaire de spécifications #
Sélectionnez explicitement yaml-openapi pour .yaml ou .yml dans la configuration des fichiers de la CLI. L’extension seule ne permet pas de distinguer une spécification d’API d’un catalogue d’application. Le gestionnaire YAML générique sélectionnerait bien davantage de chaînes ; le gestionnaire YAML avec langue à la racine exige une structure d’encapsulation différente.
Utilisez la configuration de la CLI ou GitHub pour sélectionner les fichiers et définir les chemins de destination. La traduction limitée à certaines clés via la CLI n’est pas disponible pour OpenAPI.
Validez le contrat et lisez les descriptions #
Validez le document reconstruit avec vos outils OpenAPI et comparez les chemins, les identifiants d’opération, les références, les champs obligatoires et les valeurs de schéma à ceux de la source. Lisez ensuite les descriptions affichées en regard de ce contrat. Une description de réponse qui modifie une condition ou un engagement peut induire en erreur la personne qui développe, même si la spécification reste valide.