Geração Swagger/OpenAPI para Go (Golang): go-swagger e oapi-codegen

Geração Swagger/OpenAPI para Go (Golang): go-swagger e oapi-codegen

O desenvolvimento de serviços web modernos em Go requer uma especificação rigorosa de API. OpenAPI (anteriormente conhecido como Swagger) é um padrão para descrever interfaces RESTful que permite automatizar a criação de clientes, servidores e documentação. No ecossistema Go, existem duas ferramentas-chave para geração de código a partir de especificações OpenAPI: go-swagger e oapi-codegen. Neste artigo, analisaremos detalhadamente ambas as abordagens, sua instalação e aplicação prática.

O que é OpenAPI e por que gerar código?

OpenAPI Specification (OAS) é um formato de arquivo (geralmente YAML ou JSON) que descreve endpoints, parâmetros, tipos de dados e esquemas de resposta da sua API. Em vez de escrever manualmente handlers, modelos e validação, você pode:

• Gerar código do servidor com rotas e middleware.
• Gerar um SDK cliente para outros serviços.
• Atualizar automaticamente a documentação (Swagger UI).
• Evitar dessincronização entre a especificação e a implementação.

Ferramenta nº 1: go-swagger

go-swagger é uma ferramenta poderosa, porém mais pesada, que suporta não apenas geração, mas também validação de especificações. É ideal para projetos complexos com versionamento.

Instalação do go-swagger

# Instalação via go install (Go 1.17+)go install github.com/go-swagger/go-swagger/cmd/swagger@latest

# Verificação da instalaçãoswagger version

Geração do servidor a partir da especificação

Suponha que temos um arquivo api.yaml:

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

Execute a geração do servidor:

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

Após a execução, na pasta ./gen aparecerão:

• restapi/ — handlers e rotas.
• models/ — estruturas de dados (Pet, Error, etc.).
• cmd/ — ponto de entrada da aplicação.

Exemplo de implementação de handler

package restapi

import (    "net/http"    "petstore/gen/models"    "petstore/gen/restapi/operations")

func configureAPI(api *operations.PetstoreAPI) http.Handler {    api.ListPetsHandler = operations.ListPetsHandlerFunc(        func(params operations.ListPetsParams) middleware.Responder {            pets := []*models.Pet{                {ID: 1, Name: "Buddy"},                {ID: 2, Name: "Milo"},            }            return operations.NewListPetsOK().WithPayload(pets)        },    )    return api.Serve(nil)}

Ferramenta nº 2: oapi-codegen

oapi-codegen é um gerador moderno, leve e muito rápido da equipe DeepMap. Ele suporta OpenAPI 3.0 e foca no minimalismo. É recomendado para novos projetos.

Instalação do oapi-codegen

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

Geração de tipos e servidor

Usamos a mesma especificação api.yaml. Execute:

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

A flag -generate permite escolher o que gerar:

• types — estruturas Go