Generación Swagger/OpenAPI para Go (Golang): go-swagger y oapi-codegen

Generación Swagger/OpenAPI para Go (Golang): go-swagger y oapi-codegen

El desarrollo de servicios web modernos en Go requiere una especificación estricta de la API. OpenAPI (anteriormente conocido como Swagger) es un estándar para describir interfaces RESTful que permite automatizar la creación de clientes, servidores y documentación. En el ecosistema de Go existen dos herramientas clave para generar código a partir de especificaciones OpenAPI: go-swagger y oapi-codegen. En este artículo analizaremos en detalle ambos enfoques, su instalación y aplicación práctica.

¿Qué es OpenAPI y por qué generar código?

OpenAPI Specification (OAS) es un formato de archivo (normalmente YAML o JSON) que describe los endpoints, parámetros, tipos de datos y esquemas de respuesta de tu API. En lugar de escribir manualmente los manejadores, modelos y validaciones, puedes:

• Generar código de servidor con rutas y middleware.
• Generar un SDK de cliente para otros servicios.
• Actualizar automáticamente la documentación (Swagger UI).
• Evitar la desincronización entre la especificación y la implementación.

Herramienta n.º 1: go-swagger

go-swagger es una herramienta potente, pero más pesada, que admite no solo la generación, sino también la validación de especificaciones. Es ideal para proyectos complejos con versionado.

Instalación de go-swagger

# Instalación mediante go install (Go 1.17+)go install github.com/go-swagger/go-swagger/cmd/swagger@latest

# Verificar la instalaciónswagger version

Generación del servidor a partir de la especificación

Supongamos que tenemos un archivo 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

Ejecuta la generación del servidor:

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

Después de la ejecución, en la carpeta ./gen aparecerán:

• restapi/ — manejadores y rutas.
• models/ — estructuras de datos (Pet, Error, etc.).
• cmd/ — punto de entrada de la aplicación.

Ejemplo de implementación del manejador

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)}

Herramienta n.º 2: oapi-codegen

oapi-codegen es un generador moderno, ligero y muy rápido del equipo de DeepMap. Es compatible con OpenAPI 3.0 y se centra en el minimalismo. Se recomienda para proyectos nuevos.

Instalación de oapi-codegen

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

Generación de tipos y servidor

Usamos la misma especificación api.yaml. Ejecuta:

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

La bandera -generate permite seleccionar qué generar:

• types — estructuras Go