Añadir y utilizar Swagger en tu servidor Go

Tiempo de lectura: 3 minutos

Hoy vamos a aprender cómo podemos añadir Swagger en nuestro proyecto Go.

Lo primero que haremos es instalar las librerías necesarias.

Instalamos http-swagger

 go get github.com/swaggo/http-swagger 

Instalamos swaggo files

go get -u github.com/swaggo/files

Instalamos Gin

go get -u github.com/swaggo/gin-swagger

Ahora vamos a documentar el código:

Primero vamos a main.go y añadimos la cabecera de la aplicación:

//Swagger
// @title           API de Ejemplo
// @version         1.0
// @description     Esta es una API para demostrar Swagger.
// @host            localhost:8080
// @BasePath        /

Importante, cuando despleguemos tenemos que cambiar localhost:8080 por la dirección URL del servidor (solo indicamos el dominio sin https y sin barra al final: dominio.com)

Después podemos comentar el resto de servicios:

GET:

// StreamingHandler maneja el flujo de datos en tiempo real basado en la entrada de "pregunta"
// @Summary Flujo de datos en tiempo real
// @Description Envía una solicitud de generación y recibe los datos en tiempo real
// @Tags streaming
// @Accept json
// @Produce text/event-stream
// @Param pregunta query string true "Pregunta a enviar al modelo"
// @Success 200 {string} string "data: Starting to receive data..."
// @Failure 400 {string} string "Pregunta no proporcionada"
// @Failure 500 {string} string "Error en la respuesta del servidor"
// @Router /streaming [get]

POST:

// CreateQuestionHandler maneja la creación de una nueva pregunta
// @Summary Crear nueva pregunta
// @Description Envía una pregunta y recibe la respuesta generada
// @Tags questions
// @Accept json
// @Produce json
// @Param question body string true "Pregunta a enviar al modelo"
// @Success 201 {string} string "Pregunta creada con éxito"
// @Failure 400 {string} string "Pregunta no proporcionada"
// @Failure 500 {string} string "Error en la respuesta del servidor"
// @Router /questions [post]

Put:

// UpdateQuestionHandler maneja la actualización de una pregunta existente
// @Summary Actualizar pregunta
// @Description Actualiza una pregunta existente con nueva información
// @Tags questions
// @Accept json
// @Produce json
// @Param id path int true "ID de la pregunta"
// @Param question body string true "Nueva pregunta"
// @Success 200 {string} string "Pregunta actualizada con éxito"
// @Failure 400 {string} string "Pregunta no proporcionada"
// @Failure 404 {string} string "Pregunta no encontrada"
// @Failure 500 {string} string "Error en la respuesta del servidor"
// @Router /questions/{id} [put]

Delete

// DeleteQuestionHandler maneja la eliminación de una pregunta existente
// @Summary Eliminar pregunta
// @Description Elimina una pregunta existente
// @Tags questions
// @Produce json
// @Param id path int true "ID de la pregunta"
// @Success 204 {string} string "Pregunta eliminada con éxito"
// @Failure 404 {string} string "Pregunta no encontrada"
// @Failure 500 {string} string "Error en la respuesta del servidor"
// @Router /questions/{id} [delete]

Estructura: Cada handler tiene una estructura similar al GET que proporcionaste, con los comentarios adecuados para la documentación Swagger.

Validación: Cada función incluye validaciones para manejar errores, como la falta de parámetros.

Lógica: La lógica de manejo de la pregunta (como almacenar, actualizar o eliminar) debe ser implementada según tu caso de uso específico.

Y ahora vamos a enlazar las rutas. Para ello vamos a nuestro manejador de rutas, en mi caso routes.go

Importamos primero la ruta de la documentacion /docs y luego el servidor swagger:

import (
	...
	_ "app/docs"

	httpSwagger "github.com/swaggo/http-swagger"
)

Ahora añadimos el manejador para el get de sawgger:

func SetupRouter() *mux.Router {
	router := mux.NewRouter()
	...

	// Documentar swagger
	router.PathPrefix("/swagger/").Handler(httpSwagger.WrapHandler)

	return router
}

Bien, pues ya tendríamos todo listo.

Y ahora para ejecutar el swagger y generar los docs:

go run github.com/swaggo/swag/cmd/swag@latest init -g main.go -o docs

Finalmente lanzamos nuestra app:

go run main.go

Y ahora abriremos:

http://localhost:8080/swagger/

En mi caso el puerto es 8080, tendrás que indicar el tuyo.