Tutorial: Generate Swagger Specification and SwaggerUI for Echo Go Web Framework

Why Echo Web Framework?

Why Swagger Specification?

Prerequisite

Steps

$ mkdir echosimple
$ mkdir docs
$ mkdir docs/echosimple
$ go mod init
$ go get -v github.com/labstack/echo/v4
package main

import (
"net/http"

"github.com/labstack/echo/v4"
"github.com/labstack/echo/v4/middleware"
)

func main() {
// Echo instance
e := echo.New()

// Middleware
e.Use(middleware.Logger())
e.Use(middleware.Recover())
e.Use(middleware.CORS())

// Routes
e.GET("/", HealthCheck)

// Start server
e.Logger.Fatal(e.Start(":3000"))
}

func HealthCheck(c echo.Context) error {
return c.JSON(http.StatusOK, map[string]interface{}{
"data": "Server is up and running",
})
}
$ go run echosimple/main.go
   ____    __ 
/ __/___/ / ___
/ _// __/ _ \/ _ \
/___/\__/_//_/\___/ v4.1.16
High performance, minimalist Go web framework
https://echo.labstack.com
____________________________________O/_______
O\
⇨ http server started on [::]:3000
package main

import (
"net/http"

"github.com/labstack/echo/v4"
"github.com/labstack/echo/v4/middleware"
)

// @title Echo Swagger Example API
// @version 1.0
// @description This is a sample server server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:3000
// @BasePath /
// @schemes http
func main() {
// Echo instance
e := echo.New()

// Middleware
e.Use(middleware.Logger())
e.Use(middleware.Recover())
e.Use(middleware.CORS())

// Routes
e.GET("/", HealthCheck)

// Start server
e.Logger.Fatal(e.Start(":3000"))
}

// HealthCheck godoc
// @Summary Show the status of server.
// @Description get the status of server.
// @Tags root
// @Accept */*
// @Produce json
// @Success 200 {object} map[string]interface{}
// @Router / [get]
func HealthCheck(c echo.Context) error {
return c.JSON(http.StatusOK, map[string]interface{}{
"data": "Server is up and running",
})
}
$ go get -v github.com/swaggo/swag/cmd/swag
$ go get -v github.com/swaggo/echo-swagger
$ swag init -g echosimple/main.go --output docs/echosimple
package main

import (
"net/http"

"github.com/labstack/echo/v4"
"github.com/labstack/echo/v4/middleware"
_ "github.com/rizalgowandy/go-swag-sample/docs/echosimple" // you need to update github.com/rizalgowandy/go-swag-sample with your own project path
echoSwagger "github.com/swaggo/echo-swagger"
)

// @title Echo Swagger Example API
// @version 1.0
// @description This is a sample server server.
// @termsOfService http://swagger.io/terms/

// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io

// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html

// @host localhost:3000
// @BasePath /
// @schemes http
func main() {
// Echo instance
e := echo.New()

// Middleware
e.Use(middleware.Logger())
e.Use(middleware.Recover())
e.Use(middleware.CORS())

// Routes
e.GET("/", HealthCheck)
e.GET("/swagger/*", echoSwagger.WrapHandler)

// Start server
e.Logger.Fatal(e.Start(":3000"))
}

// HealthCheck godoc
// @Summary Show the status of server.
// @Description get the status of server.
// @Tags root
// @Accept */*
// @Produce json
// @Success 200 {object} map[string]interface{}
// @Router / [get]
func HealthCheck(c echo.Context) error {
return c.JSON(http.StatusOK, map[string]interface{}{
"data": "Server is up and running",
})
}
e.GET("/swagger/*", echoSwagger.WrapHandler)
import (
...
_ "github.com/rizalgowandy/go-swag-sample/docs/echosimple" // you need to update github.com/rizalgowandy/go-swag-sample with your own project path
echoSwagger "github.com/swaggo/echo-swagger"
...
)
$ go run echosimple/main.go
$ curl localhost:3000/swagger/doc.json
{ 
"schemes": ["http"],
"swagger": "2.0",
"info": {
"description": "This is a sample server server.",
"title": "Echo Swagger Example API",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"name": "API Support",
"url": "http://www.swagger.io/support",
"email": "support@swagger.io"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "1.0"
},
"host": "localhost:3000",
"basePath": "/",
"paths": {
"/": {
"get": {
"description": "get the status of server.",
"consumes": [
"*/*"
],
"produces": [
"application/json"
],
"tags": [
"root"
],
"summary": "Show the status of server.",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
}
http://localhost:3000/swagger/index.html

References

Software Engineer | INTJ | Choleric | The Questioner (CD) | Creator & Advisor

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store