Golang Engineering Components Api Document Management go-swagger's swag et net/http intégration

Go-Swagger est un générateur de documents API RESTful basé sur la norme OpenAPI 2.0. Il peut générer automatiquement des documents API via des commentaires et des codes, et fournit une série d'outils de ligne de commande et de bibliothèques de modèles pratiques et rapides. Swag est une partie très importante de Go-Swagger, qui fournit la fonction de génération de documentation API en utilisant les annotations Swagger dans Golang. Cet article présente principalement les points de connaissance qui doivent être maîtrisés lorsque swag est intégré à net/http.

1. Installer

Avant de pouvoir commencer à utiliser Swag, nous devons installer les dépendances correspondantes. Saisissez la commande suivante dans le terminal :

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

Cette commande téléchargera et installera swag dans le répertoire $GOPATH/bin.

1. utiliser

Ensuite, nous pouvons utiliser Swag pour générer la documentation API correspondante. Tout d'abord, exécutez la commande suivante dans le répertoire racine de votre projet :

swag init

Cette commande lira tous // swagger:operationles fichiers avec des commentaires Swagger ( ) dans votre projet et générera automatiquement le fichier JSON de documentation de l'API Swagger (swagger.json) et la page HTML (index.html) en fonction de ces commentaires.

Ensuite, ajoutez le code suivant au fichier main.go :

package main

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

    _ "path/to/your/docs" // 导入生成的docs文件
)

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

    // 添加swagger路由
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

    // TODO: 后续代码

    r.Run()
}

Dans le code ci-dessus, nous avons d'abord utilisé _ "path/to/your/docs"le document API généré par l'importation, puis ajouté la route swagger dans la fonction principale, afin que les utilisateurs puissent http://localhost:8080/swagger/index.htmlaccéder à la page de document API que vous avez générée.

Ensuite, nous devons décrire ces API à l'aide d'annotations Swagger au-dessus des gestionnaires HTTP auxquels nous voulons exposer les API. Par exemple, lors de la diffusion d'une requête GET sous la route /user :

// swagger:operation GET /user user getuser
// ---
// summary: 获取用户信息.
// description: 根据id获取对应用户的信息.
// parameters:
// - name: id
//   in: path
//   description: 用户ID.
//   required: true
//   type: integer
// responses:
//   '200':
//     description: 成功获取到用户信息.
type GetUserInput struct {
	ID int `uri:"id" binding:"required"`
}

func getUser(c *gin.Context) {
	var input GetUserInput

	if err := c.ShouldBindUri(&input); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{
			"code": 1,
			"msg":  "bad request",
		})
		return
	}

	user, err := getUserByID(input.ID)
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{
			"code": 2,
			"msg":  "server error",
		})
		return
	}

	c.JSON(http.StatusOK, gin.H{
		"code": 0,
		"data": user,
	})
}

Dans le code ci-dessus, nous avons ajouté le commentaire Swagger avant la fonction getUser. Dans ces commentaires, nous décrivons le nom, le chemin, les paramètres et les valeurs de retour de l'API. Lorsque nous exécutons swag initla commande, Swag lira ces annotations et générera le fichier JSON de documentation de l'API Swagger correspondant.

1. Résumer

Cet article présente les points de connaissance pertinents de l'intégration wag et net/http. Grâce à l'utilisation de Swag, nous pouvons facilement générer des documents API conformes à la spécification OpenAPI pour nos projets, et les modifier et les mettre à jour facilement et rapidement. En même temps, lors de l'intégration de Swag dans net/http, il vous suffit d'ajouter simplement une route pour permettre aux utilisateurs d'accéder à la page de documentation de l'API que vous avez générée, ce qui est très pratique et pratique. J'espère que les lecteurs pourront maîtriser les connaissances de base requises pour l'intégration Swag et net/http grâce à cet article, et pourront mieux les utiliser pour améliorer l'efficacité de leur développement.