IN PROGRESS:
h3. Libs
Following the libs found which show able to generated the swagger from the code.
h4. beego_api
* https://beego.me/blog/beego_api
h4. go-swagger
* https://github.com/go-swagger/go-swagger
h5. Links/Articles
* http://bigk.me/swagger/golang/go/2017/07/30/golang-and-openapi-how-to-create-documentation-for-your-rest-api-services/
* https://labs.bawi.io/documenting-an-api-with-swagger-cb106250239f
h3. Analyse over the libs
- Shows that go-swagger it is the official one used for more people.
- Aerogear metrics project is already using it
h3. POC tests
Done locally and worked as follows.
h4. main.go
{code:java}
// API for Mobile Security Service
// Schemes: http, https
// Title: Mobile Security Service Server API
// Description: This is a sample mobile security service server.
// Version: 1.0.0
//
// Consumes:
// - application/json
//
// Produces:
// - application/json
//
// Host: localhost:3000
//
//
// swagger:meta
package main
//go:generate swagger generate spec -m -o ../../api/swagger.yaml
import (
"github.com/aerogear/mobile-security-service/pkg/config"
"github.com/aerogear/mobile-security-service/pkg/web/apps"
"github.com/aerogear/mobile-security-service/pkg/web/router"
dotenv "github.com/joho/godotenv"
"github.com/labstack/echo"
log "github.com/sirupsen/logrus"
)
func init() {
config := config.Get()
initLogger(config.LogLevel, config.LogFormat)
err := dotenv.Load()
if err != nil {
log.Info("No .env file found, using default values instead.")
}
}
func main() {
config := config.Get()
e := router.NewRouter(config)
initHandlers(e, config)
// start webserver
if err := e.Start(config.ListenAddress); err != nil {
panic("failed to start" + err.Error())
}
}
func initLogger(level, format string) {
logLevel, err := log.ParseLevel(level)
if err != nil {
log.Fatalf("log level %v is not allowed. Must be one of [debug, info, warning, error, fatal, panic]", level)
logLevel = log.InfoLevel
}
log.SetLevel(logLevel)
switch format {
case "json":
log.SetFormatter(&log.JSONFormatter{})
case "text":
log.SetFormatter(&log.TextFormatter{DisableColors: true})
default:
log.Fatalf("log format %v is not allowed. Must be one of [text, json]", format)
}
}
// Invoke handlers, services and repositories here
func initHandlers(e *echo.Echo, c config.Config) {
// Prefix api routes
apiRoutePrefix := c.ApiRoutePrefix
apiGroup := e.Group(apiRoutePrefix)
// App handler setup
appsPostgreSQLRepository := apps.NewPostgreSQLRepository()
appsService := apps.NewService(appsPostgreSQLRepository)
appsHandler := apps.NewHTTPHandler(e, appsService)
// Setup routes
router.SetAppRoutes(apiGroup, appsHandler)
}
{code}
router.go
{code:java}
func SetAppRoutes(r *echo.Group, appsHandler *apps.HTTPHandler) {
// swagger:operation GET /apps apps
//
// ---
// produces:
// - application/json
// responses:
// '200':
// description: successful operation
r.GET("/apps", appsHandler.GetApps)
{code}
After running the command `$swagger generate spec -m -o ../../api/swagger.yaml` it worked and generate the file as follows.
{code:java}
consumes:
- application/json
host: localhost:3000
info:
description: API for Mobile Security Service
version: 1.0.0
paths:
/apps:
get:
operationId: apps
produces:
- application/json
responses:
"200":
description: successful operation
produces:
- application/json
schemes:
- http
- https
swagger: "2.0"
{code}
|
|
