Para demostrar el uso de nuestras API’s usamos Postman o bien CURL en un apartado de nuestra web. Pero ¿y si tenemos la documentación como su uso en un mismo lugar y desde el mismo código?
Cuando desarrollas una API es una buena práctica documentarla, pienso que la idea de crearlas es para que vaya a ser usada a lo cual sería de buena ayuda conocer sus endpoints, parámetros de request y response.
Es muy probable que tu gestor de paquetes de Linux disponga de la librería. Sin embargo, siguiente orden podrás instalarlo usando go get
goget -u github.com/go-swagger/go-swagger/cmd/swagger
Te explicaré el uso empleando el API en Go de SimpsonGo. Aquella misma que utilizo para mi App en Android SimpsonGo que por cierto está en playStore ✌ y cuya historia de desarrollo puedes leer aquí.
Todo el código de documentación está en el código fuente.
Bien, el primer paso es crear meta
// SimpsonGo.
//
// API que sirve frases aletorias de los Simpsons. ¿Quieres ver cómo va su desarrollo? https://osmandi.now.sh/post/simpsongo
//
// Schemes: https
// Host: simpsongo.now.sh
// BasePath: /
// Version: 1.0
// License: MIT http://opensource.org/licenses/MIT
// Contact: https://osmandi.now.sh
//
//
// Consumes:
// - application/json
// - application/xml
//
// Produces:
// - application/json
// - application/xml
//
// swagger:meta
package main
Es bastante intuitivo, nombre del API, descripción, esquema, host…
Definimos el modelo del response.
// showMessage//// Esta es la estructura usada para responder con frases//// swagger:model showMessagetype showMessage struct {
// Message Mensaje o frase
Message string `json:"message" xml:"message"`
// Author Autor de la frase
Author string `json:"author" xml:"author"`
}
El paso siguiente es definir el response de uno de los endpoint el cual usa el modelo que definimos anteriormente.
// swagger:route GET / messageAleatory selectMessage//// Obtiene una frase aleatoria//// Responses:// - 200: showMessage
func selectMessage(c echo.Context) error {
// Random Number
numberRand := rand.Intn(countLinesFile())
message := parseMessage(selectLine(numberRand))
c.Response().Header().Set("Access-Control-Allow-Origin", "*")
return c.JSON(http.StatusOK, message)
}
En caso de que la respuesta sea un conjunto elementos.
// swagger:route GET /all allMessages allMessages//// Obtiene todos las frases guardades en la base de datos//// Responses:// - 200: []showMessage
func allMessages(c echo.Context) error {
messages := make([]showMessage, 0)
list := readFile()
fori := range list {
message := parseMessage(list[i])
messages = append(messages, message)
}
c.Response().Header().Set("Access-Control-Allow-Origin", "*")
return c.JSONPretty(http.StatusOK, messages, " ")
}
No solo podemos definir el estatus 200, también podemos definir los otros status http.
Primero debemos generar el formato con toda la información del API en JSON.
swagger generate spec -o ./swagger.json --scan-models
Para correrlo tenemos dos opciones:
swagger serve -F=swagger swagger.jsonswagger serve -F=redoc swagger.jsonPuedes echarle un vistazo a mi documentación de SimpsonGo con Swagger y me das un feedback.
Cuando vi la clase de JavaDoc del curso de JavaSE avanzado me estaba preguntando si existía algo así pero para las API’s de Go. Durante una semana estuve buscando y encontré SwaggerUI con otra semana para aprender a usarlo jejeje.
En mi búsqueda no encontré un tutorial en español así que sácale provecho y recuerda dejar acá abajo tus comentarios o dudas que entre la comunidad nos ayudamos.
Hasta la próxima ✌
