🙅 🆗 💰 Précisez-le. Rapport Yandex 👩🏿‍🚀 👩🏽‍🌾 👩🏽‍🏭

Une bonne spécification API aide les clients à l'utiliser. Il y a quelques mois chez Big Pytup, le développeur Yandex Alexander Bryazginbryazginnna fait une présentation sur quoi la spécification de l'API REST est basée sur un exemple d'OpenAPI + Swagger et pourquoi un tel bundle est nécessaire. À partir du synopsis, vous pouvez découvrir comment nous avons foiré la génération automatique de la spécification dans le service fini, quelles bibliothèques nous ont été utiles et quel type de réglage est autour de la spécification OpenAPI.

- Bonjour à tous, mon nom est Alexander. Je voudrais vous parler des spécifications.

Plus précisément, je voudrais aborder plusieurs sujets. Tout d'abord, quelles sont les spécifications en utilisant l'exemple des spécifications de l'API REST. De plus - comme nous avons accéléré la génération des spécifications dans notre service. Et à la fin, du bon côté - quels outils, réglage, pour utiliser les résultats de notre génération de spécifications, en utilisant un exemple d'une telle spécification comme OpenAPI et Swagger UI.

Spécifications de l'API REST

Quelles sont les spécifications et qu'est-ce que j'entends par là dans mon rapport?

Tout d'abord, c'est l'Interface Description Language, un langage pour décrire les interfaces, une description qui correspond à un format spécifique. Il peut être analysé automatiquement, car il a un format strict et des spécificités telles qu'il ne dépend pas de la langue elle-même dans laquelle l'interface est implémentée. Autrement dit, disons que vous avez un serveur Web Python, pour le langage de description d'interface, cela n'a pas d'importance.

Il existe de nombreuses langues pour spécifier les spécifications. Ce sont des spécifications pour REST, RPC, GraphQL, etc. Aujourd'hui, nous allons nous attarder sur la spécification REST.

Openapi

Parlons des spécifications en utilisant l'exemple OpenAPI.

Tout d'abord, comprenons ce qu'est OpenAPI. Il s'agit du même langage pour décrire les spécifications. En soi, il s'agit d'un fichier - au format YAML, JSON ou XML, qui l'aime le plus - avec une description de l'interface, des poignées des points de terminaison et des schémas.

Swagger

Quand on parle d'OpenAPI, on ne peut pas dire de Swagger.

Swagger est essentiellement une interface utilisateur OpenAPI qui vous permet de visualiser magnifiquement vos spécifications.

Dans Swagger, comme dans OpenAPI, il y a une description des points de terminaison qui se trouvent dans votre spécification.

Il y a une description de l'autorisation dans votre API.

Il existe une description des modèles ou des circuits avec lesquels vous manipulez dans votre API - par exemple, acceptez-les pour entrée ou renvoyez-les pour sortie.

Il y a une description des exemples et des demandes et réponses attendues de votre API.

De plus, dans votre Swagger, du fait qu'il s'agit d'une interface utilisateur et qu'il s'exécute dans votre navigateur, vous pouvez en temps réel exécuter des requêtes vers votre API ici et maintenant.

^{_{Lien depuis la diapositive}}

Avec tout cela, vous pouvez jouer sur un banc d'essai préparé par l'équipe Swagger. C'est petstore.swagger.io. Il y a un exemple de spécification, soulevé par Swagger. Vous pouvez accéder au vrai backend et toucher. Recommander.

Donc, nous disons: OpenAPI, Swagger, spécification. Mais pourquoi tout cela est nécessaire pour une personne qui écrit, disons, un backend?

Tout d'abord, les spécifications sont souvent utilisées lors de la phase de conception de notre API. Autrement dit, les gens normaux, étant arrivés à la tâche d'écrire un backend, commencent par décrire ce qu'ils veulent mettre en œuvre. Autrement dit, ils commencent à concevoir leur API, une liste de points de terminaison qu'ils souhaitent implémenter, une liste de schémas à manipuler, des paramètres, etc. Dans ce cas, les spécifications et les outils autour des spécifications sont très pratiques.

De plus, il existe un cas populaire. Pour ce que nous avons fait glisser la spécification vers nous en service? Ceci est la documentation. La disponibilité des spécifications vous donne une si bonne occasion de décrire votre API et de partager ces informations avec quelqu'un: soit avec les fournisseurs frontaux de votre équipe, soit avec des clients externes qui souhaitent s'intégrer avec vous.

De plus, étant donné que la spécification est écrite dans un certain format strict, elle peut être automatiquement traitée, c'est-à-dire engagée dans l'introspection de l'API. Et en plus, vous pouvez attraper de nombreux outils qui peuvent vous faciliter la vie. Je vous le dirai plus précisément et plus en détail plus tard.

Comment nous préparons OpenAPI

Nous avons décidé pourquoi nous avions besoin de tout cela. Parlons de la façon dont nous avons bousillé la génération de spécifications dans notre service. Tout d'abord, un peu de contexte.

Lorsque nous sommes arrivés à l'idée de réduire la spécification, nous avons fait fausse route lorsque nous avons écrit le projet, dans le sens d'un prototype avec une spécification. Nous avons déjà soulevé un backend, il volait déjà avec nous, et nous voulions partager la spécification comme moyen de documentation.

Et notre backend était soudainement en Python. Nous avons utilisé Falcon comme cadre, marshmallow comme outil de sérialisation et de désérialisation des données et webargs comme outil de validation.

En utilisant l'extrait le plus simple de l'animalerie que j'ai mentionné plus tôt, nous imaginerons à quoi pourrait ressembler notre service à l'étape où nous voulions générer une spécification.

Dans notre service, il y aurait une paire simplifiée de schémas: le type de notre animal de compagnie, c'est-à-dire la catégorie et, en fait, les animaux eux-mêmes.

Autrement dit, nous décririons plusieurs schémas sur Marshmallow. De plus, nous préparerions quelques stylos afin, par exemple, de vous inscrire et de recevoir nos favoris.

Et, en fait, ils décriraient l'application elle-même, ce qui augmenterait le point final pour la création et la réception d'animaux domestiques.

Voilà à quoi cela ressemblerait. Service assez simple.

Réfléchissons aux options dont nous disposons pour créer une configuration OpenAPI. L'option la plus simple et la plus naïve, comme je l'ai dit plus tôt, n'est qu'un fichier. Pourquoi ne faisons-nous pas ce fichier avec nos mains? Nous savons quelles données d'entrée nous avons, nous avons des points de terminaison. Cela semble évident, il suffit de prendre et d'écrire.

Mais tout d'abord, nous sommes des programmeurs. Nous n'aimons rien faire de nos mains. Nous voulons que quelque chose de standard soit généré pour nous. Deuxièmement, si nous prenions tout en charge à la main, nous devrons certainement prendre en charge les modifications d'API, ainsi qu'un fichier qui se trouve ailleurs. Comme tout service, notre produit est volatile, tout comme les spécifications.

Par conséquent, nous sommes arrivés à la conclusion que nous voulons générer une configuration OpenAPI. Compte tenu de notre pile technologique, nous avons trouvé une bibliothèque comme apispec . Apispec est une bibliothèque de fabricants, c'est-à-dire les auteurs de Marshmallow et Webargs. Ensemble, ils constituent un vaste écosystème.

Voyons comment vous pouvez utiliser apispec sur notre pile pour lui apprendre à générer une spécification pour nous.

Nous avions une ressource et un gestionnaire spécifique pour la méthode get de cette ressource. Il a une sorte de corps.

Pour enseigner l'apispec, pour lui faire savoir ce que nous faisons dans notre stylo, nous ajoutons quelque chose au docstring. Nous y ajoutons une description compréhensible pour l'homme. Dans notre cas, ceci est un exemple de réponses: parfois cela arrive, notre stylo répond avec deux cents, et dans le corps de notre réponse il y a JSON avec un schéma, Pet data model.

En utilisant l'exemple d'une post-requête, nous décrivons: en plus du fait qu'il y a une réponse 201 dans laquelle nous renvoyons Pet, il y a aussi le corps attendu de la requête qui nous vient. Et à l'intérieur de cette demande, nous attendons JSON, et nous attendons à ce que ce JSON soit au format Pet.

Nous avons ajouté des docstrings, puis nous devons apprendre à générer une spécification. Pour ce faire, nous écrivons une sorte de script, un bouton rouge et apprenons à apispec à générer une spécification pour nous. Nous déclarons un objet apispec, à partir duquel nous décrivons quelques métadonnées de notre service, puis écrivons simplement le fichier, la spécification générée au format YAML.

Voyons ce qui a été généré pour cette énorme application dans ce fichier.

Tout d'abord, dans ce fichier, il y aura une description de la version dans laquelle la spécification a été générée. Ceci est important pour que tous ceux qui interprètent cette spécification comprennent le format à interpréter. Les spécifications varient d'une version à l'autre.

De plus, il y a une description de notre service. Ce titre, cette version, peut-être y aura-t-il une description, si vous le souhaitez, puis une liste de serveurs vers lesquels vous pourrez vous rendre, tirer les stylos, voir et toucher notre backend.

De plus, les schémas de données que nous manipulons y poussent, avec une description des types, des exemples de remplissage de ces données et quelques règles. Ce sont peut-être des valeurs extrêmes, peut-être les paramètres de liaison. Vous voyez ici une liste des attributs requis.

En plus des schémas, la description des points de terminaison eux-mêmes s'y développe. Dans ce cas, la description de chaque méthode germe.

En utilisant la méthode get, nous obtenons une description de ce que nous faisons avec la méthode get.

Et exactement la description que nous avons mise dans les docstrings du point de terminaison correspondant a germé sur le post. Autrement dit, nous avons déjà reçu une sorte de fichier.

Qu'allons-nous en faire maintenant? Quelle est l'utilité? Tout d'abord, vous, en tant que propriétaires du backend, pouvez déjà donner à tous ces clients potentiels qui iront dans vos stylos, donner cette spécification. Et cela aidera les gars à s'intégrer. C'est-à-dire que le fichier que nous avons généré ne vous fait pas vous arracher les yeux. C'est assez lisible. Il peut être vu à travers les yeux et analysé d'une manière ou d'une autre.

Mais c'est aussi difficile. Voyons quels autres outils sont là pour vous simplifier la vie et quel type de réglage est autour de la spécification générée.

Brioches

Et puis nous arrivons à l'étape suivante, où nous parlerons de ce qui est une boîte à outils utile autour des spécifications en utilisant l'exemple OpenAPI.

^{_{Lien de la diapositive}}

Le premier outil dont je voudrais parler est Swagger-UI. Ci-après, je fournirai des liens vers une ressource Web où vous pouvez piquer l'outil correspondant, dans ce cas SwaggerHub, ou vers la commande pour lancer le document correspondant à l'aide de Docker.

Nous aimons tous Docker. Docker vous aide à ne pas mettre JavaScript ou Java sur le local. Prenez-le, exécutez-le avec une seule commande, et tout fonctionne pour vous.

Ainsi, Swagger-UI est, en fait, un utilitaire qui vous permet d'afficher magnifiquement vos spécifications. Comme je l'ai dit plus tôt, ceux-ci s'exécutent localement à l'aide de Docker, peut-être Swagger.

Vous pouvez afficher ou partager sur les paramètres régionaux en exécutant la spécification dans Swagger sur votre matériel. Et envoyez en outre tous vos utilisateurs potentiels à cette spécification. Elle est déjà beaucoup plus compréhensible, belle. Directement dedans, vous pouvez exécuter l'exécution des requêtes.

^{_{Lien depuis la diapositive}}

En plus de Swagger-UI, il existe un outil Swagger-editor pratique. Vous pouvez l'utiliser sur le Web, vous pouvez le récupérer sur une locale ou sur n'importe quelle machine à écrire. Il vous permet de modifier les spécifications en temps réel et de voir son affichage ici. C'est-à-dire que c'est un outil très pratique au stade de, disons, la conception d'une API, lorsque vous n'avez pas généré de spécification et que vous souhaitez en quelque sorte faire une farce ou décrire votre backend sans avoir de backend réel ou généré.

Ensuite, le merveilleux outil Prism. Je voudrais m'y attarder plus en détail. Prism est un utilitaire de Spotlight. Il vous permet, avec la spécification, d'élever le faux serveur, qui fonctionnera selon la spécification que vous lui avez donnée.

Autrement dit, dans ce cas, nous voyons le lancement de Prism en plus de la spécification, que j'ai volé juste sous le magasin Swagger. Nous voyons que Prism a trouvé tous les points finaux qui sont spécifiés dans la spécification, et a dit qu'ils les dérangent honnêtement.

Essayons de ressentir ce que Prism peut faire.

Tout d'abord, nous trouvons le stylo, essayons de le tirer et soudain nous voyons que Prism nous dit: désolé, erreur 401. Nous allons dans la spécification et voyons qu'en fait ce stylo est caché derrière l'autorisation. La section de sécurité y est clairement décrite. Dans ce document, nous voyons que la méthode d'autorisation est OAuth, et nous comprenons: en fait, Prism attendait une sorte de données d'autorisation de notre part.

Essayons de lui transférer les données d'autorisation selon le format qu'il attend. Il est clair que le jeton est en quelque sorte aérien, pour Prism, peu importe ce qu'il est par essence. Le format est important pour lui. Autrement dit, s'il attend OAuth, il attend les données d'autorisation dans un format spécifique.

Nous branlons avec autorisation et voyons déjà la 400e erreur. Nous regardons ce que nous avons dans la spécification. Dans la spécification, nous voyons que nous n'avons pas passé certains attributs requis. Passons-les.

L'attribut magique est le statut. Il est, en fait, donné selon la spécification ENUM. Si nous avions transféré un statut qui n'est pas inclus dans cet ENUM, nous aurions obtenu quatre points.

Ici, nous avons passé le statut valide et nous voyons que le backend a répondu avec un xml complètement valide avec les données. Les données de ce fichier XML sont désormais uniquement renvoyées à partir de l'exemple spécifié dans la spécification. Autrement dit, dans la spécification pour chaque champ, il existe une section comme exemple, où vous pouvez spécifier un exemple de données qui peuvent être retournées. Ici, Prism vient de les ramener.

Mais en plus du fait que vous pouvez tirer le stylo et vous attendre à ce qu'il y en ait deux cents honnêtes, il est possible de dire Prism - renvoyez-moi un code de réponse spécifique. Habituellement, dans la spécification, nous décrivons les différents comportements de notre stylo, et avec des données valides, ils ne correspondent pas toujours à deux cents. Ils peuvent rechercher, par exemple, la présence d'ID dans la base de données, pour voir qu'un tel ID n'existe pas.

Pour ce cas, nous déclarons un certain code, disons le 400e ou le 422e, à qui vous voulez. Autrement dit, avec une entrée valide, il n'y a pas toujours une sortie valide. Par conséquent, dans la spécification, nous décrivons différentes options de réponse. Et nous pouvons clairement dire en secouant le stylo Prism: cette fois j'attends que vous me répondiez, disons, la 404ème erreur. Disons que c'est un cas où je tire la poignée avec un ID, mais il n'y a pas un tel ID.

Pour résumer, quelles sont les fonctionnalités en général, en plus de celles que j'ai déjà mentionnées? Encore une fois, il s'agit d'un faux serveur que vous pouvez récupérer. Il répondra selon le cahier des charges, validera les demandes d'autorisation. Il validera également les données que vous lui avez envoyées.

En plus de valider la demande, il générera des réponses. Dans le cas le plus simple, comme je l'ai dit, cela génère des réponses par l'exemple. Il existe une deuxième option - lorsque vous la demandez explicitement: veuillez générer des réponses dynamiques. Une stratégie dynamique signifie que, selon le type, par exemple, int, elle générera des milliers, des milliards ou autre chose. Ou pour la chaîne, un hachage étrange et incompréhensible.

Aussi, lorsque j'ai dit lors de la première exécution que vous pouvez générer des données, nous nous sommes demandé: ce serait cool si Prism s'intégrait avec faker. Ceux qui ont utilisé le simulateur Python savent probablement à quel point c'est cool quand vous voulez verrouiller certaines données ou émuler des données dans la base de données.

Ainsi, Prism est écrit en JavaScript. JavaScript a également Faker.js, et Prism a une intégration automatique avec faker. Vous pouvez spécifier explicitement dans votre spécification les types de données faker que votre stylo fournira. Autrement dit, OpenAPI prend en charge un système de plug-in qui vous permet d'étendre vos spécifications afin qu'OpenAPI et l'analyseur lui-même ne s'en soucient pas. Mais s'il existe des plugins qui analysent vos spécifications, ils peuvent utiliser des champs supplémentaires.

Ainsi, Prism vous propose d'utiliser le champ optionnel du plugin X-faker. Très confortablement.

Ici, sous l'astérisque, j'ai indiqué que les rappels peuvent être décrits dans OpenAPI. Il s'agit du schéma d'interaction lorsque vous enregistrez un rappel sur un certain stylet et attendez qu'après cela, vous recevrez un rappel spécifique sur l'URL que vous avez enregistrée. Donc, Prism et il savent se mouiller.

D'intéressant: le prisme peut être élevé non seulement en mode maquette, mais aussi en mode proxy. Vous venez de mettre ce proxy devant votre vrai backend, et toutes les demandes qui passent par Prism et reviennent, Prism validera selon les spécifications.

Si certaines données - disons, entrée ou sortie, demande ou réponse - divergent, il l'écrira dans le journal. Il le fait de manière assez transparente, cela n'affecte pas le comportement réel. En général, la documentation indique qu'elle peut être facilement augmentée en production. Honnêtement, je ne l'ai pas essayé moi-même. Il y a sûrement une sorte de frais généraux, mais je ne peux toujours pas en parler. Vous pouvez sentir, essayer et dire.

De plus, grâce à ce que j'ai déjà dit, il est possible de forcer certaines demandes. Autrement dit, venez sur le faux serveur et dites: Je veux un exemple ou un type de réponse spécifique. Nous avons déjà parlé du type de réponse. Toujours dans la spécification OpenAPI, il est possible de spécifier plusieurs options de réponse et de les nommer explicitement.

Donc, vous pouvez venir dire Prism: cette fois je veux un exemple précis, la prochaine fois je veux un autre exemple.

^{_{Lien de la diapositive}}

À propos de Prism parlé. Maintenant à propos de Postman. Je l'aime tellement. Ainsi, Postman a une intégration prête à l'emploi avec OpenAPI. Vous pouvez littéralement importer la spécification OpenAPI en seulement deux clics sur les boutons. Et il créera une collection de demandes selon vos spécifications.

En même temps, il pré-préparera tous les paramètres de requête, tous les paramètres de corps, tout l'environnement et l'autorisation. Il vous suffit de terminer les données avec de vrais identifiants ou autre chose, des jetons d'autorisation. Très confortablement.

Nous passons de Postman plus loin. Nous avons parlé de Prism, il a des fonctionnalités - validation des requêtes. En fait, il existe un utilitaire distinct qui vous permet de sucer sans pitié votre backend vraiment en cours d'exécution et de voir s'il fonctionne vraiment selon les spécifications.

Dredd analyse la spécification. Il prend, tire tous les stylos et regarde ce qui lui est retourné. En général, dredd peut être traité comme une infrastructure pour écrire des tests, car toutes ses requêtes peuvent être complétées par ses hooks. Autrement dit, à partir de la boîte, vous pouvez commencer à dredd tel quel, comme je l'ai lancé ici.

Ou vous pouvez exécuter dredd en lui passant un ensemble de crochets qui fonctionnent réellement dans l'idéologie d'un test régulier. Il y a quelque chose qui monte à l'ensemble des tests, il y a des hooks qui tournent avant le test, après le test, toute l'infrastructure.

^{_{Lien de la diapositive}}

Ensuite, je veux parler plus en détail d'un tel outil de Swagger lui-même comme Swagger-codegen. En fait, c'est un peu comme un couteau suisse. Pour commencer, quel genre de pensées les gars ont-ils eu quand ils ont écrit cet instrument.

Habituellement, lorsque quelqu'un doit s'intégrer à un backend, vous décrivez rarement une demande http ici, à un certain stade, dans la logique métier. Le plus souvent, vous encapsulez le travail avec un backend spécifique dans une entité, dans le client.

Donc, les gars ont eu l'idée que, ayant une spécification, nous pouvons très clairement décrire et prédire à quoi ressemblerait le client pour ce backend. Et les gars ont fait un générateur de clients.

Essayons de démarrer la génération du client conformément aux spécifications de l'animalerie. Nous verrons que ce générateur a été généré par le client Swagger lui-même, dans lequel se trouve le client Python lui-même. Ici, dans la ligne de lancement, vous pouvez clairement voir que je génère un client en Python. En fait, il prend en charge un grand nombre de langues. Qu'est-ce qui est important ici? Les pionniers apprécieront JavaScript, les hipsters apprécieront Go. Tout ce que vous voulez.

Ainsi, en plus du client en Python, il a généré quelques documents et testé des dossiers magiques. Nous en parlerons plus tard plus en détail. Et beaucoup de sucre pour que vous puissiez envelopper ce client dans une bibliothèque prête à l'emploi. Il y a gitignore, il y a des fichiers CI, disons pour Travis, il y a du sucre pour git. Il existe des exigences, setup.py et tox.ini. Autrement dit, tout ce qui vous aide simplement à prendre, valider et envoyer ce client est déjà sous la forme d'une bibliothèque qui peut être réutilisée.

Examinons de plus près ce qu'il a généré chez le client.

Dans le client, il a généré, en plus de certains fichiers auxiliaires, deux répertoires très importants api et modèles. Dans les modèles, nous avons ces modèles de données que nous manipulons. Chaque modèle est simplement une classe Python héritée de l'objet avec __init__, qui prend toutes sortes de paramètres pour ce schéma, et des getters et setters qui changent l'état de l'objet.

En plus du modèle, des entités telles que PetApi y sont également apparues - ce ne sont que des wrappers clients sur le groupe de points de terminaison, que OpenAPI regroupe soit par balises soit par points de terminaison.

Et ce client a tous les stylos que vous pouvez contracter, transmettant des données réelles. Ensuite, ils s'envoleront vers un backend.

Qu'est-ce qui est implémenté à partir de ce client généré? De l'intéressant - l'approche contractuelle. Parlons plus de lui.

L'approche contractuelle de la programmation suggère que lorsque vous implémentez l'interaction entre le client et le serveur, vous définissez en fait toujours certaines règles, des contrats, qu'il s'agisse de données que le client donne au serveur ou de données que le serveur donne au client.

Ainsi, l'approche contractuelle vous recommande de vérifier à chaque fois en temps réel la conformité de vos données et de votre interaction avec le contrat. Si ce contrat est un schéma des données que nous transmettons, et ne répond pas à nos attentes, n'est pas satisfait, alors vous devez le dire, montrer l'erreur ici et maintenant. N'allez pas au vrai backend, n'attendez pas de quatre points, mais dites tout de suite.

Ou un autre cas: nous sommes allés au backend, avons reçu des données, mais elles ne correspondent pas à ce que nous attendions. Supposons que certains champs que nous nous attendions à voir remplis deviennent vides. Nous en parlerons ici et maintenant, et non pas lorsque nous laisserons quelque part sur la pile d'appels quelque part dans la forêt et ne découvrirons pas pourquoi quelque chose est tombé.

Ainsi, Swagger-codegen génère des clients et des modèles selon l'approche contractuelle. Il vous permet de dire en temps réel: oui, je veux que le client en exécution vérifie toutes les données pour la conformité avec les contrats. Et si le contrat n'est pas satisfait, il le dira immédiatement.

Nous avons généré une sorte de pit-client avec une approche contractuelle, mais en plus de cela, Swagger-codegen a généré des talons de documentation pour nous. En fait, ils sont assez simples, mais ils peuvent tous être tordus pour chaque modèle.

Swagger-codegen a également généré une sorte de talons de test. Tout pour que vous puissiez déployer le code généré avec un minimum d'effort et l'exécuter avec des tests, avec une intégration continue, sous la forme d'une bibliothèque avec un git, avec toutes les cloches et les sifflets.

Revoyons-le brièvement. Nous avons examiné un seul cas - un moyen de générer des clients pour l'API. De l'importante} approche contractuelle. Je voudrais dire: lorsque j'ai généré un client pour une véritable animalerie selon leurs spécifications et que je suis vraiment allé dans son backend, cette approche contractuelle a soudainement saisi les données invalides qui ont été retournées par l'animalerie.

Au début, j'ai pensé - ils sont un peu étranges. Ils ont eux-mêmes généré la spécification et le backend ne fonctionne pas correctement pour eux. Mais il me semble qu'ils l'ont fait exprès pour que nous puissions voir la puissance de l'approche contractuelle. Il n'y avait pas beaucoup de données et elles étaient clairement générées.

Aussi dans la génération de clients et dans une autre génération, vous pouvez utiliser vos propres modèles. Autrement dit, si vous souhaitez générer un client dans un certain format, vous pouvez enregistrer et préparer votre modèle et générer des clients comme vous le souhaitez. Si vous faites le tour et générez des intégrations tous les jours, cela pourrait vous plaire beaucoup.

Vous pouvez également configurer ces clients et écrire l'importation de vos modèles, plutôt que ceux générés par Swagger-codegen.

En plus de générer des clients pour l'API, vous pouvez transmettre la spécification au générateur et générer les stubs du serveur lui-même. C'est très étrange. Autrement dit, vous générez une sorte de backend qui fonctionne soi-disant conformément aux spécifications. Il est clair qu'il n'y a aucune logique commerciale là-bas. Mais peut-être que ce sera pratique comme une sorte d'échafaudage, c'est-à-dire préparer un projet avec lequel vous pouvez déjà faire quelque chose. Je ne l'ai pas utilisé, mais je recommande d'y jeter un coup d'œil - peut-être trouverez-vous quelque chose d'utile pour vous-même.

Entre autres, il vous permet de générer de la documentation au format HTML et Confluence si quelqu'un l'utilise. Les exemples que je voulais montrer pour OpenAPI se sont également arrêtés là.

^{_{Tous ces outils sont disponibles sur les deux liens ci-dessous sur la diapositive: openapi.tools etgithub.com/APIs-guru/awesome-openapi3}}

Je veux montrer les groupes de réglages autour de la spécification OpenAPI. En fait, il existe de nombreux outils. Ce ne sont que des groupes, c'est-à-dire des types d'outils que vous pouvez utiliser.

L'important ici est un convertisseur d'une spécification à une autre. Autrement dit, vous pouvez générer l'API Blueprint ou tout ce que vous voulez à partir de la spécification OpenAPI, et vice versa. Il existe une bibliothèque pour la simulation, pour la documentation. Autrement dit, tout ce dont j'ai parlé se reflétera dans ces groupes.

Il existe également un lien que vous pouvez suivre. Assurez-vous d'aller chercher.

^{_{Lien depuis la diapositive}}

Outre les outils autour d'OpenAPI, il existe des outils autour de Swagger. Il y a SwaggerHub et Swagger Inspector. Ils sont surlignés en bleu car il s'agit d'une boîte à outils Web. Vous pouvez vous y rendre directement et utiliser en tant que service le SwaggerHub et Swagger Inspector, qui sont en fait une superposition des bibliothèques suivantes: Swagger-editor, Swagger-codegen, Swagger-UI. Tout ce que nous venons de discuter.

Toutes les bibliothèques sont jaunes, elles sont open source, comme nous l'avons vu. Il existe sur GitHub, se présente sous la forme de Docker. Utilisation.

Conclusion

De quoi avons-nous discuté aujourd'hui? Spécification de l'API REST utilisant OpenAPI et Swagger comme exemples. Je tiens à souligner que OpenAPI n'est qu'une façon de décrire la spécification. Beaucoup d'entre eux. Parmi les plus intéressants, voir également l'API Blueprint. Peut-être que quelqu'un d'autre aimera quelque chose.

Nous avons également regardé Swagger. En substance, comme nous l'avons déjà dit, ce n'est qu'une belle interface utilisateur autour de la spécification, qui vous permet de la regarder et de l'explorer de manière pratique. En fait, ces outils sont également nombreux, allant des populaires ReDoc et Sphinx, et se terminant, en fait, Markdown. Autrement dit, vous pouvez générer Markdown à partir d'OpenAPI, et il sera magnifiquement affiché dans tous les GitHub, GitLab - où vous le souhaitez.

Nous avons également examiné un exemple de notre pile technologique sur la façon dont nous générons maintenant la spécification. Mais comme vous l'avez remarqué, cela est assez compliqué et peu pratique, car nous dupliquons en fait la logique métier et les docstrings.

^{_{Liens de la diapositive: FastAPI , SAFRS , rororo}}

D'intéressant, je vous conseille de regarder FastAPI. Styopa vous en dira plus à ce sujet aujourd'hui . FastAPI vous aide à générer une spécification prête à l'emploi. Vous n'y pouvez penser à rien du tout. Écrivez simplement le code et obtenez les spécifications finales.

Il existe deux autres cadres: SAFRS et rororo. Les noms, bien sûr, sont magiques. Ils fonctionnent un peu sur un modèle différent, ne vous font pas penser à la spécification et ne l'obtiennent que comme un effet secondaire. Au contraire, vous avez une spécification qui pilote les gestionnaires. Il s'agit, en gros, d'un développement axé sur les spécifications. Ils n'ont pas autant d'étoiles que FastAPI, mais il me semble qu'ils méritent attention, jetez un œil.

Et enfin, nous avons discuté du type d'utilité autour de la spécification en utilisant les exemples d'OpenAPI et de Swagger. Pour tous les points que je fais des liens, regardez bien, il y a beaucoup de choses intéressantes:

- OpenAPI / Swagger
swagger.io/docs/specification/about

- Exemple sur falcon + marshmallow + apispec
github.com/marshmallow-code/apispec
github.com/tiangolo/fastapi

- OpenAPI / Swagger
petits pains
openapi.tools swagger.io/tools swagger.io/tools/open-source/open-source-integrations github.com/APIs-guru/awesome-openapi3

Que dois - je était le message du rapport? Les gars, la rédaction de spécifications n'est pas une sorte de bureaucratie. Et ce n'est pas aussi difficile que cela puisse paraître à première vue, mais plutôt simple et fournit de nombreux outils utiles, vous ouvre de grandes opportunités.

Écrivez les spécifications. Recommander. Merci beaucoup.

Tous les codes et liens sont disponibles dans la présentation .