Swagger/OpenAPI-Generierung für Go (Golang): go-swagger und oapi-codegen

Swagger/OpenAPI-Generierung für Go (Golang): go-swagger und oapi-codegen

\n\n

Die Entwicklung moderner Webdienste in Go erfordert eine strenge API-Spezifikation. OpenAPI (früher bekannt als Swagger) ist ein Standard zur Beschreibung von RESTful-Schnittstellen, der die Automatisierung der Erstellung von Clients, Servern und Dokumentation ermöglicht. Im Go-Ökosystem gibt es zwei wichtige Werkzeuge zur Generierung von Code aus OpenAPI-Spezifikationen: go-swagger und oapi-codegen. In diesem Artikel werden wir beide Ansätze, ihre Installation und praktische Anwendung im Detail besprechen.

\n\n

Was ist OpenAPI und warum Code generieren?

\n

Die OpenAPI Specification (OAS) ist ein Dateiformat (normalerweise YAML oder JSON), das die Endpunkte, Parameter, Datentypen und Antwortschemata Ihrer API beschreibt. Anstatt Handler, Modelle und Validierungen manuell zu schreiben, können Sie:

\n

\n
• Servercode mit Routen und Middleware generieren.
\n
• Ein Client-SDK für andere Dienste generieren.
\n
• Die Dokumentation automatisch aktualisieren (Swagger UI).
\n
• Eine Desynchronisation zwischen Spezifikation und Implementierung vermeiden.
\n

\n\n

Werkzeug Nr. 1: go-swagger

\n

go-swagger ist ein leistungsstarkes, aber schwereres Werkzeug, das nicht nur die Generierung, sondern auch die Validierung von Spezifikationen unterstützt. Es eignet sich ideal für komplexe Projekte mit Versionierung.

\n\n

Installation von go-swagger

\n

# Installation über go install (Go 1.17+)\ngo install github.com/go-swagger/go-swagger/cmd/swagger@latest\n\n# Installation überprüfen\nswagger version

\n\n

Server aus einer Spezifikation generieren

\n

Angenommen, wir haben eine Datei api.yaml:

\n

openapi: "3.0.0"\ninfo:\n  title: Pet Store\n  version: "1.0.0"\npaths:\n  /pets:\n    get:\n      summary: Alle Haustiere auflisten\n      operationId: listPets\n      responses:\n        '200':\n          description: Eine Liste von Haustieren\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

Führen Sie die Servergenerierung aus:

\n

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

\n

Nach der Ausführung erscheinen im Ordner ./gen:

\n

\n
• restapi/ — Handler und Routen.
\n
• models/ — Datenstrukturen (Pet, Error usw.).
\n
• cmd/ — Einstiegspunkt der Anwendung.
\n

\n\n

Beispiel für die Implementierung eines Handlers

\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

Werkzeug Nr. 2: oapi-codegen

\n

oapi-codegen ist ein moderner, leichter und sehr schneller Generator vom Team DeepMap. Es unterstützt OpenAPI 3.0 und konzentriert sich auf Minimalismus. Es wird für neue Projekte empfohlen.

\n\n

Installation von oapi-codegen

\n

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

\n\n

Generierung von Typen und Server

\n

Wir verwenden dieselbe Spezifikation api.yaml. Führen Sie aus:

\n

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

\n

Das Flag -generate ermöglicht die Auswahl, was generiert werden soll:

\n

\n
• types — Go-Strukturen und Typen.
\n
• server — Server-Schnittstellen und Handler-Wrapper.
\n