Tutorial: Generate Swagger Specification and SwaggerUI for Echo Go Web Framework
By: Rizal Widyarta Gowandy
Tags: Swagger, Swagger Ui, Go, Echo, Open Api

Prerequisite

You need to install Go version ≥1.12 in your machine.

Steps

Create folders for development, we will call the app echosimple.

$ mkdir echosimple

$ mkdir docs

$ mkdir docs/echosimple

2. Initialize go mod for go vendor system.

$ go mod init

3. Pull the Echo library.

$ go get -v github.com/labstack/echo/v4

4. Inside echosimple folder, create a new file main.go and copy the code below.

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",

})

}

5. Run the app.

$ go run echosimple/main.go

You should see an output like below.

____ __

/ __/___/ / ___

/ _// __/ _ \/ _ \

/___/\__/_//_/\___/ v4.1.16

High performance, minimalist Go web framework

https://echo.labstack.com

____________________________________O/_______

O\

⇨ http server started on [::]:3000

It means our server is up and running on port 3000.

6. Update our main.go by adding declarative comments format. These comments will be used later to automatically generate Swagger Specification. You can learn more about the declarative comments format using the link in the reference.

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",

})

}

7. Pull swagger libraries.

$ go get -v github.com/swaggo/swag/cmd/swag

$ go get -v github.com/swaggo/echo-swagger

8. Generate the Swagger Specification.

$ swag init -g echosimple/main.go --output docs/echosimple

If the operation is successful, you should see 3 new files inside folder docs/echosimple. These files are:

docs.go => Requires to generate SwaggerUI.

swagger.json => The Swagger Specification in json file format.

swagger.yaml => The Swagger Specification in yaml file format.

If you use Confluence to distribute your documentation, you could create a new file inside Confluence and choose to add OpenAPI Specification. Then copy and paste the swagger.yaml content inside.

9. Update main.go to add SwaggerUI.

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",

})

}

As you can see, there are 2 important things we add on our main.go.

A new route for SwaggerUI.

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

New imports for the generated docs.go and swag library. Don’t forget to replace the github.com/rizalgowandy/go-swag-sample path with your project path.

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"

...

)

10. Finally, run the app again.

$ go run echosimple/main.go

11. Now try, the call the new added route.

$ curl localhost:3000/swagger/doc.json

You should see output like.

{

"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

}

}

}

}

}

}

}

12. Open the SwaggerUI in the browser using this URL.

You should output like.

Voilà, and we are done. We successfully created a simple Go web server using Echo framework, and generate the Swagger Specification and SwaggerUI.

References