Utilisez Swagger pour générer automatiquement des documents API dans Beego

Utilisez Swagger dans Beego pour générer automatiquement des documents API

À mesure que la technologie Internet devient de plus en plus mature, de plus en plus d'entreprises commencent à transformer numériquement leurs modèles commerciaux, et les API, en tant qu'élément important de la transformation numérique, sont également devenues de plus en plus importantes. Lors du développement d'API, en plus d'assurer la sécurité et la fiabilité de l'API, la manière de permettre à d'autres ingénieurs de développement front-end et back-end de comprendre et d'utiliser rapidement l'API qu'ils ont développée est également un élément très important. Cet article expliquera comment utiliser l'outil Swagger pour générer automatiquement des documents API lors de l'utilisation du framework Beego pour développer des API afin de faciliter l'appel et l'utilisation d'autres ingénieurs de développement.

Qu'est-ce que Swagger ?

Swagger est une spécification et un ensemble d'outils d'API open source qui visent à simplifier et standardiser le développement et l'utilisation des API. Il peut générer automatiquement des interfaces interactives entre les développeurs, les consommateurs et les documents, et fournit de nombreuses fonctions de document d'aide visuelle.

Pourquoi utiliser Swagger ?

Certaines API nécessitent une documentation et des descriptions pour aider à comprendre leur utilisation et comment les appeler. L'utilisation de Swagger peut simplifier et générer automatiquement ces documents. L'utilisation de l'outil Swagger peut rendre les documents API plus beaux, plus standardisés et plus faciles à lire une fois générés. Le format obligatoire de Swagger peut également aider les développeurs à concevoir et à mettre en œuvre des API conformes aux spécifications standardisées, économisant ainsi du temps et de l'énergie.

Utiliser Swagger dans Beego

1. Ajouter des dépendances

Pour utiliser Swagger dans un projet Beego, vous devez d'abord ajouter les dépendances de la bibliothèque Swagger au projet. Il peut être installé via la commande suivante :

go get -u github.com/swaggo/swag/cmd/swag
go get -u github.com/swaggo/gin-swagger
go get -u github.com/swaggo/gin-swagger/swaggerFiles

2. Modifier les commentaires Swagger

Dans le framework Beego, nous utilisons les commentaires dans le code du routeur pour expliquer les paramètres de l'API, les types de requêtes, les valeurs de retour et d'autres informations, qui sont requis lors de l'utilisation de Swagger Ajoutez des balises de spécification Swagger à ces commentaires pour générer automatiquement la documentation de l'API.

Ce qui suit est un exemple simple :

// @Summary  获取一个用户信息
// @Description 通过ID获取一个用户信息
// @Accept  json
// @Produce  json
// @Param   id     path    int     true        "用户ID"
// @Success 200 {object} models.User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
    // ...
}

Dans les commentaires, nous avons ajouté quelques balises de spécification spéciales :

• @Résumé : Aperçu des méthodes API
• @Description : Description détaillée des méthodes API
• @Accepter : Contenu accepté -Type de type
• @Produce : Type de contenu de réponse de réponse
• @Param : Paramètres de demande, y compris le nom du paramètre, l'emplacement, le type de données, s'il est requis et la description.
• @Success : code d'état HTTP et type de valeur de retour d'une réponse réussie, qui peut également inclure des tableaux, des structures et d'autres informations.
• @Router : Chemin de requête et méthode de requête.

Vous pouvez ajouter plus de balises pour compléter la description de l'API si nécessaire.

3. Générer automatiquement la documentation

Après avoir ajouté les commentaires de spécification Swagger au code, exécutez la commande suivante dans le répertoire racine du projet pour générer la documentation de l'API :

swag init

Cette commande sera générée dans le répertoire du projet Un dossier docs , qui contiendra la documentation API générée et les fichiers de ressources statiques.

4. Utilisez SwaggerUI pour afficher la documentation de l'API

Si nous envoyons la documentation générée directement aux développeurs front-end, cela leur exercera une pression inutile. Afin de rendre la documentation de l'API plus conviviale et plus facile à utiliser, nous pouvons introduire SwaggerUI pour afficher la documentation de l'API.

Nous devons d'abord copier les fichiers de ressources statiques SwaggerUI dans notre projet. Ensuite, nous pouvons créer un routeur avec le chemin /swagger/*any pour associer SwaggerUI à notre projet :

r.StaticFS("/swagger", http.Dir("docs"))

Ensuite, dans le navigateur, visitez http:/. /localhost:8080/swagger/index.html pour voir la documentation de l'API générée automatiquement.

Résumé

En utilisant Swagger dans Beego, vous pouvez standardiser la définition de l'API via des annotations et générer de superbes documents API pour une utilisation facile par les développeurs. Dans le même temps, l’introduction de SwaggerUI peut simplifier davantage l’affichage et l’interaction des API et accélérer le développement.

Références :

https://www.cnblogs.com/wuyun-blog/p/10540875.html

https://github.com/swaggo/gin-swagger

https://github.com / swaggo/swag

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!