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

Rizal Widyarta Gowandy

Jun 20, 2020·4 min read

Why Echo Web Framework?

Echo is one of the most popular frameworks for Go. Echo positions itself as a high performance and minimalist web framework. It’s simple to use.

Why Swagger Specification?

Writing a specification is a meticulous process in Software Engineering. Regardless, it’s necessary if we want our API being used by others. It helps others to integrate without API with more ease. The better the documentation the easier others will integrate it into their system. In order to tackle this problem, we should follow a standardized way to create API documentation in the industry, the OpenAPI Specification or formerly known as the Swagger Specification.

The OpenAPI Specification, formerly known as the Swagger Specification, is the world’s standard for defining RESTful interfaces. The OAS enables developers to design a technology-agnostic API interface that forms the basis of their API development and consumption.

Prerequisite

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

Steps

1. 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.

http://localhost:3000/swagger/index.html

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

• Source: https://github.com/rizalgowandy/go-swag-sample
• Declarative Comment Format: https://github.com/swaggo/swag#declarative-comments-format