swagger

利用插件，对api自动生成文档

1 .go get -u github.com/swaggo/swag/cmd/swag
2 .go get -u github.com/swaggo/gin-swagger
3 .go get -u github.com/swaggo/gin-swagger/swaggerFiles

作用

1 .在写代码的时候按照一定的规则写一些注释
2 .提供一个线上的可供浏览的api文档
3 .主要提供以下信息

1 .http方法
2 .url路径
3 .http消息体，参数和类型
4 .返回的参数
5 .请求和返回的媒体类型

4 .可以通过api描述的请求参数来构建请求
5 .

使用

1 .文档：应用整体的注释
2 .https://swaggo.github.io/swaggo.io/declarative_comments_format/general_api_info.html

3 .单个api的注释
4 .https://swaggo.github.io/swaggo.io/declarative_comments_format/api_operation.html

使用步骤

1 .main.go

// @title 陈江河
// @version 0.0.1
// @description  这是一个测试
// @BasePath /v1

// 应用整体的注释

2 .router.go

"github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"
//这俩个是库

_ "../docs"
//这是生成的注释文件夹

// 添加api查看网页的路由
router.GET("/swagger/*any",ginSwagger.WrapHandler(swaggerFiles.Handler))

3 .每一个函数的上面写注释

// @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} string "ok"
// @Failure 404 {object} string "ok"
// @Router /testapi/get-string-by-int/{some_id} [get]
func getIndex()

4 .在mian.go的根目录使用swag init 生成一个docs文件，里面的docs.go是上面impot进去的那个文件

文档语法

1 .@Summary 简单描述API的功能
2 .@Description api详细描述
3 .@Tags api所属分类
4 .@Accept api接收参数的格式
5 .@Prduce 输出的数据格式
6 .@Param:参数。分为6个字段

1 .参数名称
2 .参数在HTTP请求中的位置（body,path,query）
3 .参数类型 string,int,bool
4 .是否是必选 true,false
5 .参数描述 
6 .选项 用的default来指定默认值

7 .@Success:成功返回数据格式，4个字段

1 .HTTP返回code
2 .返回数据类型
3 .返回数据模型
4 .说明
5 . //@Success 200 {string} string  "ok"

8 .@Failure:失败返回模式

1 .@Failure 404 {object} string "ok"
2 .同上

9 .路由格式

1 .@Router /testapi/get-string-by-int/{some_id} [get]
2 .api路径
3 .HTTP方法

插件的原理

1 .把函数前面的一段注释识别出来，按照格式解析成一个json配置文件
2 .再开一个网页，读取这个配置文件来输出
3 .