Utilisation de SwaggerUI dans Golang pour l'automatisation de la documentation en ligne des API

Utilisation de SwaggerUI dans Golang pour l'automatisation de la documentation en ligne des API

L'utilisation d'API (Application Programming Interfaces) est devenue un élément nécessaire dans le développement d'applications modernes. L'API facilite la séparation front-end et back-end, les microservices et les applications cloud. Cependant, une bonne API ne se contente pas d’implémenter des fonctionnalités, elle est également conviviale et facile à utiliser. C’est pour cette raison que les API documentées deviennent de plus en plus importantes. L'avantage de la documentation en ligne est que vous pouvez en apprendre davantage sur l'API avant de l'utiliser.

Dans cet article, nous présenterons comment utiliser SwaggerUI pour enregistrer la documentation de l'API et comment automatiser ce processus dans Golang pour faciliter la maintenance, fournir une documentation lisible et permettre aux autres équipes et partenaires de comprendre votre API.

SwaggerUI est un outil populaire pour créer de la documentation pour les API, générer une documentation interactive sur les API, décrire les API de manière visuelle et peut générer à la fois une documentation lisible par l'homme et du JSON ou YAML lisible par machine. SwaggerUI s'intègre à de nombreux langages de programmation, dont Golang.

Tout d'abord, vous devez utiliser l'implémentation Golang de SwaggerUI - Swag. Swag est un outil de documentation API automatisé qui combine les annotations du langage Go et les annotations Swagger pour générer automatiquement des documents Swagger 2.0.

Étape 1 : Installez Swag

Téléchargez et installez Swag à l'aide de la commande suivante dans terminal/cmd :

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

Étape 2 : Ajoutez des annotations Swagger dans le code

Ajoutez des annotations Swagger dans le code pour décrire l'API.

Ajoutez une annotation Swagger dans le commentaire au-dessus de la fonction de gestionnaire HTTP, par exemple :

// GetByID godoc
// @Summary Get user details by ID
// @Description Get user details by ID
// @Tags user
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} model.User
// @Failure 400 {object} ErrorResponse
// @Router /users/{id} [get]
func GetByID(c *gin.Context) {
    //…code here…
}

Étape 3 : Générez le fichier Swagger JSON

Générez le fichier Swagger JSON à la racine de votre base de code à l'aide de la commande suivante :

swag init

Cette commande utilisera les annotations Swagger dans le code et générera des fichiers Swagger JSON. Vous pouvez également l'ajouter dans le Makefile de votre projet.

Étape 4 : Intégrer SwaggerUI

Swag utilise SwaggerUI comme frontal pour afficher les documents API dans le navigateur. Nous devons inverser statiquement les fichiers de SwaggerUI vers notre application.

Supposons que notre application Golang s'exécute sur le port 8080. La version de SwaggerUI que nous utiliserons est la v3.31.1. Nous pouvons le télécharger depuis la page officielle de SwaggerUI GitHub par :

curl -L https://github.com/swagger-api/swagger-ui/archive/v3.31.1.tar.gz -o swagger-ui.tar.gz
tar -xf swagger-ui.tar.gz

Cela générera le dossier swagger-ui dans le répertoire local, qui contient tous les fichiers de SwaggerUI. Nous utiliserons nginx comme serveur proxy inverse (vous pouvez utiliser Apache, Caddy, etc.), démarrez nginx avec la commande suivante dans terminal/cmd :

nginx -c /path/to/nginx.conf

Dans le fichier nginx.conf, nous devons ajouter ce qui suit :

http {
  server {
    listen 8081; # 访问静态文件的端口
    server_name _;
    root /path/to/swagger-ui/dist;

    location / {
      try_files $uri $uri/ @go;
    }

    location @go {
      proxy_redirect off;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_pass http://127.0.0.1:8080; # 代理请求的端口
    }

    location /swagger-ui/ {
      try_files $uri $uri/ =404;
    }
  }
}

Dans la configuration nginx ci-dessus, nous ajoutons le dossier statique SwaggerUI /swagger-ui/dist au répertoire racine du serveur nginx en tant que fichiers statiques. Nous transmettons toutes les requêtes à localhost:8080 (notre propre application) en les transmettant au port. 8081 est le port d'écoute. Nous visualisons et utilisons SwaggerUI en visitant http://localhost:8081/swagger-ui/.

Étape 5 : Afficher la documentation de l'API

Visitez http://localhost:8081/swagger-ui/ dans votre navigateur, l'application SwaggerUI affichera le dossier statique SwaggerUI présent dans le répertoire racine. Vous pouvez trouver une liste de toutes les API bien documentées sur cette page. Cliquez sur la documentation API que vous souhaitez consulter pour l'afficher à droite. Le site Web fournit une interface conviviale API pour tester et visualiser la documentation de l'API directement sur l'API. Au cours de ce processus, l'interface graphique affiche les informations détaillées automatiquement extraites par les annotations Swagger, telles que la fourniture des paramètres de cette API, les informations sur le corps, la version de l'API, le format de l'API, etc. Cela vous fera gagner beaucoup de temps et d'énergie dans la rédaction de documents.

Conclusion

La documentation API est un outil important dans le processus de conception et de développement d'API, nous devons donc prendre en compte les API documentées lors de la création d'applications. Grâce à l'outil d'automatisation Swag, nous pouvons facilement automatiser la documentation des API dans Golang. Il est également très pratique d'utiliser SwaggerUI comme outil de visualisation pour afficher et tester les API documentées. Cela aidera les autres équipes et partenaires de collaboration et leur permettra de mieux comprendre notre API.

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!