Generación de Swagger/OpenAPI para Go (Golang): guía completa

Generación de Swagger/OpenAPI para Go (Golang)

Al desarrollar servicios web en Go (Golang), una de las tareas clave es crear documentación API de calidad y actualizada. Swagger (ahora conocido como OpenAPI) se ha convertido en el estándar de la industria para describir interfaces RESTful. En este artículo, analizaremos las principales herramientas para generar especificaciones OpenAPI en el ecosistema Go, su instalación, configuración y aplicación práctica.

¿Por qué es importante OpenAPI para el desarrollador de Go?

OpenAPI permite crear una descripción legible por máquina de tu API, que se puede utilizar para:

• Generación automática de bibliotecas cliente en diferentes lenguajes
• Creación de documentación interactiva (Swagger UI)
• Validación de solicitudes entrantes y salientes
• Pruebas de API con herramientas como Postman o Insomnia

Principales bibliotecas para generar OpenAPI en Go

1. swaggo/swag — la opción más popular

La biblioteca swaggo/swag es el estándar de facto para generar documentación Swagger en Go. Funciona basándose en anotaciones en los comentarios del código.

Instalación:

go get -u github.com/swaggo/swag/cmd/swaggo get -u github.com/swaggo/gin-swagger  // para el framework Gingo get -u github.com/swaggo/files

Ejemplo de uso con Gin:

package main

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

// @title           My API// @version         1.0// @description     Ejemplo de API en Go con 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 devuelve una lista de usuarios// @Summary      Obtener lista de usuarios// @Description  Devuelve todos los usuarios del sistema// @Tags         users// @Accept       json// @Produce      json// @Success      200  {array}   User// @Router       /users [get]func GetUsers(c *gin.Context) {    users := []User{{ID: 1, Name: "Iván"}}    c.JSON(200, users)}

type User struct {    ID   int    `json:"id" example:"1"`    Name string `json:"name" example:"Iván"`}

Después de escribir el código, ejecuta el comando:

swag init

Esto creará la carpeta docs con los archivos swagger.json y swagger.yaml.

2. go-swagger — una herramienta potente pero más compleja

go-swagger proporciona no solo la generación de documentación a partir del código, sino también el proceso inverso: generación de código a partir de la especificación.

Instalación:

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

Ejemplo de generación de servidor a partir de una especificación:

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

Generación de documentación a partir del código:

// swagger:route GET /users users listUsers// Devuelve una lista de usuarios.// responses://   200: usersResponse

func ListUsersHandler(w http.ResponseWriter, r *http.Request) {    // implementación}

3. oapi-codegen — enfoque moderno con generación de código

La biblioteca oapi-codegen permite generar tipos, esqueletos de servidor y clientes basados en una especificación OpenAPI.

Instalación:

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

Ejemplo de uso:

Primero, crea un archivo api.yaml:

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