Génération Swagger/OpenAPI pour Go (Golang) : go-swagger et oapi-codegen

Génération Swagger/OpenAPI pour Go (Golang) : go-swagger et oapi-codegen

\n\n

Le développement de services web modernes en Go nécessite une spécification d'API rigoureuse. OpenAPI (anciennement connu sous le nom de Swagger) est un standard de description d'interfaces RESTful qui permet d'automatiser la création de clients, de serveurs et de documentation. Dans l'écosystème Go, il existe deux outils clés pour générer du code à partir de spécifications OpenAPI : go-swagger et oapi-codegen. Dans cet article, nous analyserons en détail les deux approches, leur installation et leur application pratique.

\n\n

Qu'est-ce qu'OpenAPI et pourquoi générer du code ?

\n

OpenAPI Specification (OAS) est un format de fichier (généralement YAML ou JSON) qui décrit les endpoints, les paramètres, les types de données et les schémas de réponse de votre API. Au lieu d'écrire manuellement les handlers, les modèles et la validation, vous pouvez :

\n

\n
• Générer le code serveur avec les routes et middleware.
\n
• Générer un SDK client pour d'autres services.
\n
• Mettre à jour automatiquement la documentation (Swagger UI).
\n
• Éviter la désynchronisation entre la spécification et l'implémentation.
\n

\n\n

Outil n°1 : go-swagger

\n

go-swagger est un outil puissant mais plus lourd, qui prend en charge non seulement la génération, mais aussi la validation des spécifications. Il est idéal pour les projets complexes avec versionnage.

\n\n

Installation de go-swagger

\n

# Installation via go install (Go 1.17+)\ngo install github.com/go-swagger/go-swagger/cmd/swagger@latest\n\n# Vérification de l'installation\nswagger version

\n\n

Génération du serveur à partir de la spécification

\n

Supposons que nous ayons un fichier api.yaml :

\n

openapi: "3.0.0"\ninfo:\n  title: Pet Store\n  version: "1.0.0"\npaths:\n  /pets:\n    get:\n      summary: List all pets\n      operationId: listPets\n      responses:\n        '200':\n          description: A list of pets\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  $ref: '#/components/schemas/Pet'\ncomponents:\n  schemas:\n    Pet:\n      type: object\n      properties:\n        id:\n          type: integer\n        name:\n          type: string

\n\n

Exécutez la génération du serveur :

\n

swagger generate server -f api.yaml -A petstore -t ./gen

\n

Après exécution, dans le dossier ./gen, vous trouverez :

\n

\n
• restapi/ — handlers et routes.
\n
• models/ — structures de données (Pet, Error, etc.).
\n
• cmd/ — point d'entrée de l'application.
\n

\n\n

Exemple d'implémentation d'un handler

\n

package restapi\n\nimport (\n    "net/http"\n    "petstore/gen/models"\n    "petstore/gen/restapi/operations"\n)\n\nfunc configureAPI(api *operations.PetstoreAPI) http.Handler {\n    api.ListPetsHandler = operations.ListPetsHandlerFunc(\n        func(params operations.ListPetsParams) middleware.Responder {\n            pets := []*models.Pet{\n                {ID: 1, Name: "Buddy"},\n                {ID: 2, Name: "Milo"},\n            }\n            return operations.NewListPetsOK().WithPayload(pets)\n        },\n    )\n    return api.Serve(nil)\n}

\n\n

Outil n°2 : oapi-codegen

\n

oapi-codegen est un générateur moderne, léger et très rapide de l'équipe DeepMap. Il prend en charge OpenAPI 3.0 et se concentre sur le minimalisme. Il est recommandé pour les nouveaux projets.

\n\n

Installation de oapi-codegen

\n

go install github.com/deepmap/oapi-codegen/v2/cmd/oapi-codegen@latest

\n\n

Génération des types et du serveur

\n

Utilisons la même spécification api.yaml. Exécutez :

\n

oapi-codegen -generate types,server -package petstore api.yaml > petstore.gen.go

\n

Le flag -generate permet de choisir ce qui est généré :

\n

\n
• types — structures Go