Génération Swagger/OpenAPI pour Go (Golang) : guide complet

Génération Swagger/OpenAPI pour Go (Golang)

Lors du développement de services web en Go (Golang), l'une des tâches clés est la création d'une documentation API de qualité et à jour. Swagger (maintenant connu sous le nom d'OpenAPI) est devenu la norme industrielle pour la description des interfaces RESTful. Dans cet article, nous examinerons les principaux outils de génération de spécifications OpenAPI dans l'écosystème Go, leur installation, leur configuration et leur application pratique.

Pourquoi OpenAPI est-il important pour le développeur Go ?

OpenAPI permet de créer une description lisible par machine de votre API, qui peut être utilisée pour :

• La génération automatique de bibliothèques clientes dans différents langages
• La création de documentation interactive (Swagger UI)
• La validation des requêtes entrantes et sortantes
• Le test de l'API avec des outils comme Postman ou Insomnia

Principales bibliothèques pour la génération OpenAPI en Go

1. swaggo/swag — le choix le plus populaire

La bibliothèque swaggo/swag est la norme de facto pour la génération de documentation Swagger en Go. Elle fonctionne sur la base d'annotations dans les commentaires du code.

Installation :

go get -u github.com/swaggo/swag/cmd/swaggo get -u github.com/swaggo/gin-swagger  // pour le framework Gingo get -u github.com/swaggo/files

Exemple d'utilisation avec Gin :

package main

import (    "github.com/gin-gonic/gin"    "github.com/swaggo/gin-swagger"    "github.com/swaggo/files"    _ "your-module/docs" // package généré)

// @title           My API// @version         1.0// @description     Exemple d'API en Go avec Swagger// @host            localhost:8080// @BasePath        /api/v1

func main() {    r := gin.Default()        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))        r.GET("/api/v1/users", GetUsers)    r.Run(":8080")}

// GetUsers retourne la liste des utilisateurs// @Summary      Obtenir la liste des utilisateurs// @Description  Retourne tous les utilisateurs du système// @Tags         users// @Accept       json// @Produce      json// @Success      200  {array}   User// @Router       /users [get]func GetUsers(c *gin.Context) {    users := []User{{ID: 1, Name: "Ivan"}}    c.JSON(200, users)}

type User struct {    ID   int    `json:"id" example:"1"`    Name string `json:"name" example:"Ivan"`}

Après avoir écrit le code, exécutez la commande :

swag init

Cela créera un dossier docs avec les fichiers swagger.json et swagger.yaml.

2. go-swagger — un outil puissant mais plus complexe

go-swagger offre non seulement la génération de documentation à partir du code, mais aussi le processus inverse — la génération de code à partir de la spécification.

Installation :

go get -u github.com/go-swagger/go-swagger/cmd/swagger

Exemple de génération de serveur à partir d'une spécification :

swagger generate server -f ./swagger.yaml -A my-api

Génération de documentation à partir du code :

// swagger:route GET /users users listUsers// Retourne la liste des utilisateurs.// responses://   200: usersResponse

func ListUsersHandler(w http.ResponseWriter, r *http.Request) {    // implémentation}

3. oapi-codegen — une approche moderne avec génération de code

La bibliothèque oapi-codegen permet de générer des types, des stubs serveur et des clients à partir d'une spécification OpenAPI.

Installation :

go get -u github.com/deepmap/oapi-codegen/cmd/oapi-codegen

Exemple d'utilisation :

Créez d'abord un fichier api.yaml :

openapi: "3.0.0"info:  title: My API  version: "1.0"paths:  /users:    get:      oper