Integrate swagger in the gin project to generate interface documents

Swagger

Swagger is a RESTFUL interface document online automatic generation + functional testing function software. Swagger is a standardized and complete framework for generating, describing, invoking and visualizing RESTful web services. The goal is to have the client and the file system update the file at the same speed as the server, with methods, parameters and models tightly integrated into the server.

To put it simply, swagger is an intermediate software that can generate interface development documents according to the resutful style and supports testing.

1. Download and install

Download and install swag in your gin project

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

It should be noted that starting from Go 1.17 and later, go get does not recommend using the installation executable file. So versions after Go 1.17 can use go install

go install github.com/swaggo/swag/cmd/swag@latest

Then download gin-swagger

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

Two, use

1. Add the following comments to the main function of the project

// @title gvb_server API文档     //这个是生成的文档的标题
// @version 1.0				    //文档自定义版本
// @description API文档         //详情
// @host 127.0.0.01:8080       //端口号
// @BasePath /                //基本路径

2. Execute the swag init command on the command line , then you can see the docs file generated in the project

insert image description here

3. Then import the newly generated docs package in the main function, and the path generated by swag init

insert image description here

Then we can configure parameters on the api interface we wrote to generate our swagger document

4. Interface configuration parameters

insert image description here

Meaning of most parameters:

// @Tags        每个API操作的标记列表，以逗号分隔。
// @Summary     一个简短的操作总结。
// @Description  操作行为的详细解释。
// @Param data query SettingsUri	false	以空格分隔的参数。
// @Router /api/settings/:name [put] 用空格分隔的路径定义。路径,[httpMethod]
// @Produce json  api可以生成的MIME类型列表。值必须与Mime类型中描述的一致。
// @Success 200 {object} res.Response{data=string} 以空格分隔的成功响应。返回代码或默认值，{参数类型}，数据类型，注释

Please add a picture description
For more specific parameters, see: official documents

5. Access

After the interface annotation parameters are configured, execute swag init , and then you can see the swagger document with api test.

Visit: http://localhost:8080/swagger/index.html

Note: remember to start your project

insert image description here

configuration complete