Comment installer swag pour générer la documentation de l'API Golang

Swag est un outil permettant de créer rapidement des applications Go qui génère automatiquement la documentation Swagger. Les développeurs peuvent générer automatiquement la documentation de l'API en ajoutant simplement quelques commentaires à leur code. Swag prend en charge la génération de documents API conformément aux normes API RESTful, ainsi que la génération des formats Markdown et HTML.

Dans cet article, nous présenterons comment installer et utiliser Swag dans Golang.

Étape 1 - Installer Swag

Swag peut être installé à partir de GitHub à l'aide de la commande go get Utilisez la commande suivante pour installer Swag :

$ go get github.com/swaggo/swag/cmd/swag

Une fois l'installation terminée, vous pouvez trouver le fichier binaire "swag" dans le $. Chemin GOPATH/bin. Désormais, nous pouvons continuer à utiliser Swag pour générer de la documentation API.

Étape 2 - Générer la documentation de l'API

Swag nécessite des commentaires de code spéciaux pour générer correctement la documentation de l'API. Voici quelques exemples de commentaires :

// @Summary 创建用户
// @Description 创建一个新用户
// @Tags 用户管理
// @Accept json
// @Produce json
// @Param user body User true "用户信息"
// @Success 200 {string} string "成功"
// @Failure 400 {string} string "请求错误"
// @Failure 500 {string} string "服务器内部错误"
// @Router /users [post]
func CreateUser(c *gin.Context) {
    // ...
}

Les commentaires ci-dessus décrivent une API sur la façon de créer un utilisateur. Swag recherche ces commentaires spéciaux dans le code puis crée la documentation.

Exécutez la commande suivante pour générer de la documentation :

$ swag init

Cela analysera votre application et générera des fichiers Swagger JSON et l'interface utilisateur Swagger.

Étape 3 - Ajouter l'interface utilisateur de Swagger

L'interface utilisateur de Swagger fournit une interface interactive pour visualiser et tester les API. Nous pouvons ajouter l'interface utilisateur Swagger à notre application Web.

// main.go
package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    "github.com/swaggo/files" // swagger embed files
    "github.com/swaggo/gin-swagger" // gin-swagger middleware
    _ "github.com/user/repo/docs" // docs is generated by Swag CLI, you have to import it.
)

func main() {
    r := gin.New()

    // use ginSwagger middleware to serve the API docs
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    //...
}

Supposons que vous ayez généré la documentation à l'aide de Swag. Vous pouvez maintenant consulter la documentation de l'API en ouvrant le lien suivant dans votre navigateur :

http://localhost:8080/swagger/index.html

Il s'agit de l'interface utilisateur Web de Swagger que vous pouvez utiliser pour afficher et tester l'API.

Résumé

Dans cet article, nous avons présenté comment installer et utiliser Swag dans Golang. Avec les annotations et les commandes de Swagger, vous pouvez facilement générer de la documentation API. Swag rend l'ensemble du processus rapide et facile, et la documentation utilisant Swag s'intègre bien à l'interface utilisateur de Swagger

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!