Utiliser OpenAPI/Swagger pour rédiger la documentation de l'API en langage Go

Ces dernières années, avec le développement continu de la technologie Internet, l'importance des interfaces API Web est devenue de plus en plus importante, et la rédaction de documents API est devenue une partie importante du travail de développement. En langage Go, nous pouvons utiliser OpenAPI/Swagger pour écrire des documents API.

OpenAPI/Swagger est une spécification d'API et une chaîne d'outils qui peuvent nous aider à créer et à décrire des interfaces API conformes au style architectural RESTful. Il contient un ensemble de langages de description d'API standardisés et une série d'outils qui peuvent nous aider à générer automatiquement des documents API, du code client et un cadre de serveur.

Dans le langage Go, vous pouvez utiliser l'implémentation officielle "swag" de Swagger's Go pour générer rapidement des documents API. Ci-dessous, nous apprendrons comment utiliser swag pour rédiger la documentation de l'API.

Tout d'abord, nous devons ajouter du swag au projet. Vous pouvez utiliser la commande suivante pour l'ajouter au projet :

go get -u github.com/swaggo/swag/cmd/swag

Après avoir installé swag, nous devons le faire. ajoutez-le au fichier main.go Importez les packages liés au swag :

import (
    "github.com/swaggo/files"
    "github.com/swaggo/gin-swagger"
    "github.com/gin-gonic/gin"
)

// 注册swag
func setUpSwagger(engine *gin.Engine) {
    engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

func main() {
    // 初始化 gin 引擎
    engine := gin.Default()
    setUpSwagger(engine)
    router.LoadRouters(engine)
    _ = engine.Run()
}

Ensuite, nous pouvons utiliser des commentaires swagger dans les commentaires de l'interface pour décrire l'interface. Par exemple :

// User register router
// @Summary User register router
// @Description User register router
// @Tags Users
// @Accept  json
// @Produce  json
// @Param user_in body models.NewUser true "user info"
// @Success 200 {string} json "{"code":200,"data":null,"msg":"Register successful"}"
// @Failure 400 {string} json "{"code":400,"msg":"Bad Request"}"
// @Router /users/register [post]
func Register(c *gin.Context) {
    name := c.PostForm("name")
    password := c.PostForm("password")
    ...
}

Dans les commentaires, nous utilisons des annotations fanfaronnes :

• @Résumé : Informations récapitulatives de l'interface
• @ Description : Description détaillée de l'interface
• @Tags : Balise d'interface
• @Accepter : Demande d'interface Content-Type
• @Produce : Réponse d'interface Contenu- Type
• @Param : description du paramètre d'interface, y compris l'emplacement du paramètre, le nom du paramètre, s'il s'agit d'un paramètre obligatoire, description du paramètre et exemple de paramètre
• @Succès : description de la réponse réussie de l'interface , Peut inclure le code de réponse, les informations de réponse et la structure des données de réponse
• @Failure : Description de la réponse en cas d'échec de l'interface, peut également inclure le code de réponse et les informations de réponse

Enfin, nous Vous devez utiliser la commande swag init dans le répertoire racine du projet pour générer la documentation de l'API. La documentation sera générée dans le répertoire docs.

swag init

Maintenant, nous pouvons consulter la documentation de l'API en visitant http://localhost:8080/swagger/index.html.

En général, utiliser OpenAPI/Swagger pour rédiger des documents API peut nous aider à décrire l'interface plus clairement et à la rendre plus facile à lire et à comprendre. La bibliothèque swag du langage Go peut générer rapidement des documents API, nous permettant ainsi de développer plus efficacement.

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!