Repolode
Enviar
swaggo

swaggo/swag

Herramienta de Go que genera documentación de API Swagger 2.0 a partir de anotaciones en los comentarios del código fuente de Go.

Ver en GitHub
Estrellas
13,048
Forks
1,492
Issues abiertos
482
Último commit
el mes pasado

¿Qué es?

Swag analiza comentarios con un formato especial en el código Go, como los que aparecen sobre funciones manejadoras y definiciones de structs, y genera documentación Swagger 2.0 en los archivos swagger.json, swagger.yaml y docs.go. Los desarrolladores añaden anotaciones como @Summary, @Param, @Success y @Router sobre sus manejadores, y ejecutan swag init para volver a generar la especificación.

La salida generada se puede mostrar con Swagger UI mediante paquetes de middleware para frameworks web populares de Go, como Gin, Echo, Fiber, net/http, chi y Hertz. Los campos de los structs pueden llevar etiquetas con ejemplos, restricciones de validación, enumeraciones y alternativas para tipos personalizados. Swag también incluye el comando swag fmt, que da formato a los comentarios con anotaciones.

Funciones clave

  • 01Genera especificaciones Swagger 2.0 en JSON, YAML y como paquete de documentación de Go.
  • 02Documenta endpoints mediante anotaciones en comentarios sobre las funciones manejadoras de Go.
  • 03Admite parámetros de solicitud, respuestas, encabezados, definiciones de seguridad y etiquetas.
  • 04Lee las etiquetas de los campos de los structs para obtener ejemplos, reglas de validación y enumeraciones.
  • 05Ofrece middleware para Gin, Echo, Fiber, net/http, chi y otros frameworks.
  • 06Incluye el comando swag fmt para dar formato a los comentarios con anotaciones.

Casos de uso

  • Generar documentación de API para un servicio REST en Go sin tener que mantener a mano un archivo OpenAPI independiente.
  • Publicar una página interactiva de Swagger UI para un backend de Gin o Echo.
  • Mantener la documentación de la API sincronizada con el código de los manejadores durante las compilaciones de CI.

Inicio rápido

  1. 1

    Instala la CLI swag con Go

    go install github.com/swaggo/swag/cmd/swag@latest
  2. 2

    Añade anotaciones de API a los comentarios del código fuente de Go

  3. 3

    Ejecuta swag init en la raíz del proyecto que contiene main.go para generar la documentación

    swag init

Antes de usarlo

  • Solo genera documentación Swagger 2.0, no OpenAPI 3.x.
  • Es necesario escribir las anotaciones en comentarios de Go y volver a generar la documentación tras los cambios.

Temas

#golang#swagger#openapi#api-documentation#rest-api#code-generation#annotations#swagger2

Preguntas frecuentes

¿Qué es swag?
Herramienta de Go que genera documentación de API Swagger 2.0 a partir de anotaciones en los comentarios del código fuente de Go. Swag analiza comentarios con un formato especial en el código Go, como los que aparecen sobre funciones manejadoras y definiciones de structs, y genera documentación Swagger 2.0 en los archivos swagger.json, swagger.yaml y docs.go. Los desarrolladores añaden anotaciones como @Summary, @Param, @Success y @Router sobre sus manejadores, y ejecutan swag init para volver a generar la especificación.
¿swag es gratuito? ¿Qué licencia tiene?
swag es open source bajo la licencia MIT. Revisa los términos de la licencia antes de usarlo en productos comerciales.
¿swag sigue mantenido?
Actualizado en los últimos 6 meses. El último commit de swag fue el 30 sept 2026.
¿Para qué puedo usar swag?
Generar documentación de API para un servicio REST en Go sin tener que mantener a mano un archivo OpenAPI independiente. Publicar una página interactiva de Swagger UI para un backend de Gin o Echo. Mantener la documentación de la API sincronizada con el código de los manejadores durante las compilaciones de CI.
¿Cómo se instala swag?
Instala la CLI swag con Go: go install github.com/swaggo/swag/cmd/swag@latest Añade anotaciones de API a los comentarios del código fuente de Go Ejecuta swag init en la raíz del proyecto que contiene main.go para generar la documentación: swag init
¿Dónde consigo swag?
El código fuente y las instrucciones de instalación están en GitHub: https://github.com/swaggo/swag

Resumen generado por IA a partir del README del proyecto. Las estadísticas de GitHub se actualizan a diario.

Proyectos relacionados