整合Swagger

What is Swagger

• Swagger 是 描述使用JSON表示的RESTful API 接口文档描述语言，实现了自动文档，代码生成和测试用例功能

Get Swagger（Gin）

• go get -u github.com/swaggo/swag/cmd/swag
• import("github.com/swaggo/files" ginSwagger "github.com/swaggo/gin-swagger")

Prepare Swagger

• 1. 在根目录执行swag init 生doc文件
• 2. 在main写入项目介绍

     // @title Tets Swaggper项目接口文档
     // @version 1.0
     // @description Go web Swagger
     // @termsOfService http: //swagger.io/terms/
     
     // @contact.name Piwriw
     // @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 127.0.0.1:8084
     // @BasePath /api/v1

• 3. 引入swagger

        import(	"github.com/swaggo/files"
     ginSwagger "github.com/swaggo/gin-swagger"
     _ "bluebell/docs"// 引入项目，重要)

• 4. route 放行 r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

How to use Swagger

函数入口写入注释

// GetPostListHandler2 升级版帖子列表接口
// @Summary 升级版帖子列表接口
// @Description 可按社区按时间或分数排序查询帖子列表接口
// @Tags 帖子相关接口
// @Accept application/json
// @Produce application/json
// @Param Authorization header string false "Bearer 用户令牌"
// @Param object query models.ParamPostList false "查询参数"
// @Security ApiKeyAuth
// @Success 200 {object} _ResponsePostList
// @Router /posts2 [get]

注释介绍

• Tags: 实现对API分组
• Accept: 接收的参数类型,支持表单元素（mpdf）和JSON
• Produce: 反馈的Response，支持

  Source Type	声明
  application/json	json
  text/xml	xml
  text/plain	plain
  html	html
  multipart/form-data	mpfd
  application/x-www-form-urlencoded	x-www-form-urlencoded
  application/vnd.api+json	json-api
  application/x-json-stream	json-stream
  application/octet-stream	octet-stream
  image/png	png
  image/jpeg	jpeg
  image/gif	gif

• Param: @Param 1.参数名 2.参数类型 3.参数数据类型 4.是否必须 5.参数描述 6.其他属性
  • 参数类型:path、query 、formData
  • 参数数据类型：string (string)、integer (int, uint, uint32, uint64、number (float32)、boolean (bool)
  • 其他属性：

    //枚举
    // @Param enumstring query string false "string enums" Enums(A, B, C)
    // @Param enumint query int false "int enums" Enums(1, 2, 3)
    // @Param enumnumber query number false "int enums" Enums(1.1, 1.2, 1.3)
    
    值添加范围
    // @Param string query string false "string valid" minlength(5) maxlength(10)
    // @Param int query int false "int valid" mininum(1) maxinum(10)
    
    设置默认值
    // @Param default query string false "string default" default(A)

• Success:@Success 1.HTTP响应码 {2.响应参数类型} 3.响应数据类型 4.其他描述
  • 2.响应参数类型 / 3.响应数据类型:
• Router: @Router /path/to/handle [HTTP方法] 不加基础路径

How to close swagger

• 1. 注释代码：r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
• 2. 配置环境变量: r.GET("/swagger/*any", ginSwagger.DisablingWrapHandler(swaggerFiles.Handler,"NAME_ENV_OF_SWAGGER"))