Ouvrir les spécifications de l'API avec plusieurs fichiers YAML

Tous ceux qui ont déjà documenté une API REST savent ce que cela fait d'écrire un fichier YAML entier avec toutes ces ressources, chemins, requêtes et schémas, mais tout à coup, vous vous retrouvez à garder un fichier dans lequel la dernière ligne comporte 5 chiffres. Oui, c'est douloureux.

Comme les meilleures applications sont celles que nous avons créées nous-mêmes, je me suis retrouvé exactement au même endroit en train de documenter une API au travail et j'ai beaucoup cherché pour ne pas trouver une seule solution viable à ce problème, c'est là que nos instincts de programmeur entrent en jeu. et nous passons cinq fois plus de temps que nous étions censés créer un nouvel outil pour nous-mêmes. C'est exactement ce que j'ai fait et je souhaite partager avec vous tous un tout nouvel outil écrit en Go pour fusionner vos fichiers YAML sur un seul fichier boss à utiliser comme spécification OpenAPI.

Présentation : GOpenAPI

GOpenAPI (Golang OpenAPI) est un outil qui utilise un fichier appelé dirs.json pour analyser les fichiers et les répertoires (oui, des répertoires entiers valant yaml) en un seul fichier swagger.yaml à la fin de l'exécution.

Vous pouvez vérifier le code source ici. Notez que le référentiel est également un modèle qui peut être cloné et utilisé comme brouillon pour créer votre première spécification OpenAPI avec cet outil (assurez-vous simplement de conserver le dossier gopenapi si vous ne souhaitez pas l'installer via go install, sinon il est complètement amovible)

Comment ça marche (et est-ce que je le fais fonctionner)

Simple, une fois que vous exécutez gopenapi, il lit le fichier dirs.json et commence à créer une spécification OpenAPI avec tous les fichiers et dossiers qui y sont déclarés. Notez que le dirs.json utilisera des fichiers pour les clés uniques telles que les informations, les serveurs et la sécurité ainsi qu'une clé appelée modèle (qui est juste un fichier yaml OpenAPI vierge)

Les ressources et les clés difficiles à conserver dans un seul fichier (comme les chemins, les schémas et les requêtes) peuvent être stockées dans des dossiers, et celles-ci peuvent également être mentionnées à l'aide de la balise #ref commune sur OpenAPI, car elles sont toutes aller au même fichier après la fusion.

Ce projet est également livré avec un index.html qui peut être servi de manière statique et il interagit également avec le bundle officiel Swagger UI contenu dans le dossier dist.

C'est tout les amis

J'espère que cet outil conviendra à tous ceux qui (tout comme moi) ont cherché dans de nombreux référentiels Reddits et Github sans trouver l'outil qu'ils recherchaient. Eh bien, maintenant vous l'avez et il est entièrement open source ce qui signifie que, si vous voyez une amélioration ou un problème qui peut être résolu, je n'y réfléchirai pas à deux fois avant de collaborer avec vous pour le résoudre. De plus, je suis assez naïf sur Golang donc il y a peut-être beaucoup à améliorer sur ce projet, je vais essayer de le maintenir à jour et de l'améliorer constamment (puisque je vais aussi beaucoup l'utiliser maintenant)

Merci d'avoir lu et j'espère que celui-ci vous sera utile de la même manière qu'il m'a été utile ;)

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!