Swagger/OpenAPI-Generierung für Go (Golang): Vollständige Anleitung

Swagger/OpenAPI-Generierung für Go (Golang)

Bei der Entwicklung von Webdiensten in Go (Golang) ist die Erstellung einer qualitativ hochwertigen und aktuellen API-Dokumentation eine der Hauptaufgaben. Swagger (heute bekannt als OpenAPI) hat sich zum Industriestandard für die Beschreibung von RESTful-Schnittstellen entwickelt. In diesem Artikel betrachten wir die wichtigsten Werkzeuge zur Generierung von OpenAPI-Spezifikationen im Go-Ökosystem, deren Installation, Konfiguration und praktische Anwendung.

Warum ist OpenAPI für Go-Entwickler wichtig?

OpenAPI ermöglicht die Erstellung einer maschinenlesbaren Beschreibung Ihrer API, die für Folgendes verwendet werden kann:

• Automatische Generierung von Client-Bibliotheken in verschiedenen Sprachen
• Erstellung einer interaktiven Dokumentation (Swagger UI)
• Validierung eingehender und ausgehender Anfragen
• Testen der API mit Tools wie Postman oder Insomnia

Wichtige Bibliotheken zur OpenAPI-Generierung in Go

1. swaggo/swag — die beliebteste Wahl

Die Bibliothek swaggo/swag ist der De-facto-Standard für die Generierung von Swagger-Dokumentation in Go. Sie basiert auf Annotationen in Code-Kommentaren.

Installation:

go get -u github.com/swaggo/swag/cmd/swaggo get -u github.com/swaggo/gin-swagger  // für das Gin-Frameworkgo get -u github.com/swaggo/files

Beispiel mit Gin:

package main

import (    "github.com/gin-gonic/gin"    "github.com/swaggo/gin-swagger"    "github.com/swaggo/files"    _ "your-module/docs" // generiertes Paket)

// @title           My API// @version         1.0// @description     Beispiel-API in Go mit 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 gibt eine Liste von Benutzern zurück// @Summary      Liste der Benutzer abrufen// @Description  Gibt alle Benutzer des Systems zurück// @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"`}

Nachdem Sie den Code geschrieben haben, führen Sie den Befehl aus:

swag init

Dies erstellt einen Ordner docs mit den Dateien swagger.json und swagger.yaml.

2. go-swagger — leistungsstark, aber komplexeres Werkzeug

go-swagger bietet nicht nur die Generierung von Dokumentation aus Code, sondern auch den umgekehrten Prozess – die Codegenerierung aus einer Spezifikation.

Installation:

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

Beispiel für die Generierung eines Servers aus einer Spezifikation:

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

Generierung von Dokumentation aus Code:

// swagger:route GET /users users listUsers// Gibt eine Liste von Benutzern zurück.// responses://   200: usersResponse

func ListUsersHandler(w http.ResponseWriter, r *http.Request) {    // Implementierung}

3. oapi-codegen — moderner Ansatz mit Codegenerierung

Die Bibliothek oapi-codegen ermöglicht die Generierung von Typen, Server-Stubs und Clients basierend auf einer OpenAPI-Spezifikation.

Installation:

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

Anwendungsbeispiel:

Erstellen Sie zunächst eine Datei api.yaml:

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