Gin Practice Serialization 8 Add Swagger to It

  api, Api documentation, golang, swagger

Add Swagger to it.

A good oneAPI's, must be inseparable from a goodAPIDocument

To develop pure handwritingAPIDocument, does not exist: =)

Project address:https://github.com/EDDYCJY/go …

Install swag

1、go get

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

If$GOPATH/binNot joined$PATHIn, you need to execute the move of its executable file to$GOBINunder

mv $GOPATH/bin/swag /usr/local/go/bin

2、gopm get

This package has referencesgolang.orgIf there is no scientific internet connection, you can use the baggopmPerform installation

gopm get -g -v github.com/swaggo/swag/cmd/swag

cd $GOPATH/src/github.com/swaggo/swag/cmd/swag

go install

Similarly, move its executable file to$GOBINunder

Verify that the installation was successful

$ swag -v
swag version v1.1.1

Install gin-swagger

$ go get -u github.com/swaggo/gin-swagger

$ go get -u github.com/swaggo/gin-swagger/swaggerFiles

Note: All three packages are of a certain size. Installation needs to wait for a while or scientific Internet access is required.

Initialization

Write API notes

SwaggerIt is necessary to write the corresponding comments or annotations to the method, and then use the generator to automatically generate the description file

gin-swaggerExamples given:

// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string    "ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]

We can refer toSwaggerNote specifications and examples to write

// @Summary 新增文章标签
// @Produce  json
// @Param name query string true "Name"
// @Param state query int false "State"
// @Param created_by query int false "CreatedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddTag(c *gin.Context) {
// @Summary 修改文章标签
// @Produce  json
// @Param id path int true "ID"
// @Param name query string true "ID"
// @Param state query int false "State"
// @Param modified_by query string true "ModifiedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags/{id} [put]
func EditTag(c *gin.Context) {

Refer to for commentsgo-gin-example. To ensure the latest swag syntax is obtained

generate

We enteredgin-blogIn the root directory of the project, execute the initialization command

[$ gin-blog]# swag init
2018/03/13 23:32:10 Generate swagger docs....
2018/03/13 23:32:10 Generate general API Info
2018/03/13 23:32:10 create docs.go at  docs/docs.go

After completion, it will be generated under the root directory of the project.docs

docs/
├── docs.go
└── swagger
    ├── swagger.json
    └── swagger.yaml

We can checkdocs.goIn the filedocVariables, notes and descriptions written in our documents in detail
docs.go

Verification

You’re done. Visithttp://127.0.0.1:8000/swagger/index.html, viewAPIIs the document generated correctly

图片描述

References

This series of sample codes

This series of catalogues