Partager:
){kind=small}
Lorna est une ingénieure en informatique qui a la manie incurable de bloguer. Elle tente d'apprivoiser les mots et le code à parts égales.
OpenAPI facilite les intégrations
Temps de lecture : 4 minutes
Nous prenons notre documentation destinée aux développeurs très sérieusement, en particulier notre Référence API. La documentation de référence est générée à partir d'une description lisible par machine de chaque API, en format OpenAPI . L'utilisation d'un format textuel lisible par machine facilite la maintenance des documents. C'est très bien pour nous, les responsables de la documentation, mais en quoi cela vous aide-t-il, vous, l'utilisateur ? Je suis heureux que vous ayez posé la question !
Jetez un coup d'œil à l'une de nos pages de référence sur les API. Vous y trouverez un bouton intitulé "Download OpenAPI 3 Specification" et si vous cliquez dessus, vous recevrez le cadeau de YAML. Vous pouvez également trouver toutes nos spécifications dans le dossier definitions/ de notre dépôt GitHub Spécifications de l'API Dépôt GitHub.
L'utilisation d'un format de description d'API standard comme OpenAPI vous permet d'accéder à de nombreux outils différents qui comprennent ces fichiers. Je vais vous montrer quelques-unes des choses que je préfère faire avec une spécification OpenAPI !
Lorsque vous essayez une API que vous ne connaissez pas, il peut être frustrant d'essayer de fouiller dans la documentation pour comprendre comment formuler une requête particulière. Postman prend en charge l'importation de fichiers de spécifications OpenAPI et les transforme en une collection de demandes d'API prêtes à l'emploi. C'est un excellent moyen d'essayer une nouvelle API sans avoir à passer trop de temps à lire la documentation et à copier les noms des champs dans mon client HTTP.
Je suis un grand fan de cette approche et je l'utilise très fréquemment, même sur des API que je connais si bien que je pourrais taper les commandes curl les yeux bandés. C'est un moyen tellement rapide d'interagir correctement avec une API et je le trouve très utile.
Lorsque je voyage, je me retrouve parfois sans connexion internet fiable. Si j'ai le fichier spec d'OpenAPI localement (spoiler : j'ai toujours les fichiers spec localement, je travaille beaucoup sur ce repo !), alors je peux utiliser un des outils de documentation d'OpenAPI pour créer des documents que je peux utiliser sur mon ordinateur portable.
Une option consiste à utiliser l'outil que nous utilisons nous-mêmes, à savoir Nexmo OAS Renderer. Il s'agit d'un outil open-source basé sur Ruby que nous avons créé et publié nous-mêmes. Il n'est pas lié à nos spécifications, je l'utilise principalement pour nos propres API, mais il devrait fonctionner avec n'importe quel fichier de spécifications OpenAPI v3 valide.
L'autre approche que j'utilise parfois est un autre outil open-source, cette fois en NodeJS, appelé ReDoc. Là encore, il est utile pour créer une documentation HTML à partir d'une spécification OpenAPI. Essayez les deux options et choisissez celle que vous préférez !
La description de l'API contient des informations sur tous les aspects de l'API. Il y a tellement d'informations, en fait, que vous pourriez faire une très bonne imitation de cette API avec tous les détails qui sont inclus.
Une très bonne imitation de l'API à partir d'une spécification OpenAPI, c'est exactement ce que fait Prism de Stoplight fournit. C'est un outil NodeJS ; installez-le avec npm et démarrez-le localement, et vous avez votre propre copie privée de l'API d'un fichier de spécification OpenAPI !
Je m'en sers le plus souvent pendant le développement, lorsque je suis susceptible d'appeler plusieurs fois le même point de terminaison de l'API, afin de m'assurer que je traite correctement les différentes réponses. Un serveur fictif est à la fois plus rapide qu'une API distante distante et beaucoup moins cher. Il n'y a pas non plus de limites de débit. Pour tous ceux qui intègrent une API, les outils tels que les serveurs fictifs sont un atout considérable. En tant que fournisseur d'API, nous n'avons pas besoin de créer ou de prendre en charge un bac à sable pour que les utilisateurs puissent développer leurs intégrations dans un espace sûr ; c'est un avantage secondaire de l'utilisation d'OpenAPI.
J'ai sélectionné trois éléments qui, selon moi, font une grande différence pour les utilisateurs d'API lorsque leur fournisseur d'API met à disposition les spécifications OpenAPI. Vonage n'est pas particulièrement remarquable dans la publication des descriptions d'API ; je m'attendrais à ce que la plupart des fournisseurs d'API modernes fassent de même. J'espère que vous avez quelques idées pour améliorer votre prochaine intégration d'API. Faites-nous savoir si vous utilisez déjà l'une de ces approches, ou quelle est celle que vous aimeriez essayer ensuite ?
Curieux d'en savoir plus sur OpenAPI et nos outils ? Voici quelques lectures complémentaires :
L'initiative OpenAPI : https://www.openapis.org
Le meilleur endroit pour trouver des outils à utiliser avec OpenAPI : https://openapi.tools
Postman pour importer une spécification afin de créer une collection de requêtes à utiliser : https://postman.com
Prism, le serveur fictif : https://stoplight.io/open-source/prism
Plus de documents spécifiques à Vonage sur OpenAPI, y compris des informations plus détaillées sur l'utilisation de Postman et Prism, et la génération de documents : /getting-started/concepts/openapi