[Golang/Swagger] Apply Swagger to describe the information API on Golang

Sau khi chúng ta thực hiện code xong 1 api thì chúng ta cần note lên 1 swagger để các teams khác integrate sẽ dễ dàng hơn

Với echo framework thì chúng ta sẽ sử dụng echo-swagger

Bạn sẽ cần chạy các command dưới đây, cùng vị trí với file main.go

go get -d github.com/swaggo/swag/cmd/swag

tiếp đến bạn chạy câu lệnh swag init để nó generate ra các file docs của swagger.

swag init

Tiếp theo bạn cần thêm:
_ "github.com/swaggo/echo-swagger/example/docs" // docs is generated by Swag CLI, you have to import it.

Tiếp đến là bạn gõ:

go get -u github.com/swaggo/echo-swagger

Tiếp theo nếu bạn bị issues “no required module provides package github.com/alecthomas/template”

GOROOT=C:\Program Files\Go #gosetup
GOPATH=C:\Users\mrnim\go #gosetup
"C:\Program Files\Go\bin\go.exe" build -o C:\Users\mrnim\AppData\Local\JetBrains\GoLand2023.2\tmp\GoLand\___go_build_jougan.exe jougan #gosetup
docs\docs.go:11:2: no required module provides package github.com/alecthomas/template; to add it:
    go get github.com/alecthomas/template

Compilation finished with exit code 1

Bạn sẽ cần pull package xuống

PS C:\Users\mrnim\GolandProjects\jougan> go get -u github.com/alecthomas/template
go: added github.com/alecthomas/template v0.0.0-20190718012654-fb15b899a751

OK giờ bạn cần thêm một số thứ vào file main.go

// @title Jougan API
// @version 1.0
// @description This is a sample server Petstore 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

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

Tiếp đến bạn sửa từng Handler đang nhận request từ API

Chúng ta sẽ breakdown config bên dưới:

// SignUp godoc
// @Summary Test Donwnload File
// @Description	Measure Download File and Save to Disk
// @Tags inspect
// @Accept  json
// @Produce  json
// @Param data body model.DownloadFile true "measure"
// @Success 200 {object} model.Response
// @Failure 400 {object} model.Response
// @Router /inspect/download-url [post]

• Summary: Short description of the endpoint, “Test Download File”.
• Description: Longer description, “Measure Download File and Save to Disk”.
• Tags: Categorize the endpoint under “inspect”.
• Param: Annotation is used to describe a parameter for the API endpoint in Swagger documentation:
  • data: The name of the parameter.
  • body: The location of the parameter (in the request body).
  • model.DownloadFile: values are used to request
  • true: Indicates the parameter is required.
  • "measure": this value is used to respond.

and

Xong bạn chạy lại swag init
và truy cập: http://localhost:1994/swagger/index.html

Notice:

Nếu các bạn không muốn force link của swagger thì bạn cần bỏ 2 dòng này:

// @host petstore.swagger.io
// @BasePath /v2