go-swagger注解使用

书接上文 ：https://blog.csdn.net/qq_38371367/article/details/122982405

对与swagger 单个api的注释位置，其实对于函数位置其实是无所谓的，你注释写在什么方法上都行，因为在生成swagger文件的时候，是根据你指定的包去扫描的，去扫描这个包里面的go文件，上面的func是否有相关注释，有注释，就能当成一个api，所以并不仅仅限制于 func(ctx *gin.context) 这样的函数，写在handle函数上面是为了方便于handle一一对应，对于程序员来说方便寻找，以及方便修改接口的同时修改swagger

swagger的核心就是，获取项目的swagger api信息，将swagger信息通过项目路由出去

swagegr与其他web项目的结合也就是为了方便路由，对于获取项目的swagger api 可以使用注释以及 swag init命令的形式获取swag init命令的详细使用如下：

swag init -h
NAME:
   swag init - Create docs.go

USAGE:
   swag init [command options] [arguments...]

OPTIONS:
   --generalInfo value, -g value          API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
   --dir value, -d value                  API解析目录 (默认: "./")
   --exclude value                        解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
   --propertyStrategy value, -p value     结构体字段命名规则，三种：snakecase,camelcase,pascalcase (默认: "camelcase")
   --output value, -o value               文件(swagger.json, swagger.yaml and doc.go)输出目录 (默认: "./docs")
   --parseVendor                          是否解析vendor目录里的go源文件，默认不
   --parseDependency                      是否解析依赖目录中的go源文件，默认不
   --markdownFiles value, --md value      指定API的描述信息所使用的markdown文件所在的目录
   --generatedTime                        是否输出时间到输出文件docs.go的顶部，默认是
   --codeExampleFiles value, --cef value  解析包含用于 x-codeSamples 扩展的代码示例文件的文件夹，默认禁用
   --parseInternal                        解析 internal 包中的go文件，默认禁用
   --parseDepth value                     依赖解析深度 (默认: 100)
   --instanceName value                   设置文档实例名 (默认: "swagger")

只有–generalInfo value, -g value 通用api注释文件位置 的值是跟–dir value, -d value 要扫描的api注释文件所在包是关联的，如果-g 使用相对位置，那么是相对于扫描的包位置，其他都是相对于当前执行的脚本位置

swag注解开发方法 swagger主文件注解-通用API信息

注释	说明	示例
title	必填 应用程序的名称。	// @title Swagger Example API
version	必填 提供应用程序API的版本。	// @version 1.0
description	应用程序的简短描述。	// @description This is a sample server celler server.
tag.name	标签的名称。	// @tag.name This is the name of the tag
tag.description	标签的描述。	// @tag.description Cool Description
tag.docs.url	标签的外部文档的URL。	// @tag.docs.url https://example.com
tag.docs.description	标签的外部文档说明。	// @tag.docs.description Best example documentation
termsOfService	API的服务条款。	// @termsOfService http://swagger.io/terms/
contact.name	公开的API的联系信息。	// @contact.name API Support
contact.url	联系信息的URL。 必须采用网址格式。	// @contact.url http://www.swagger.io/support
contact.email	联系人/组织的电子邮件地址。 必须采用电子邮件地址的格式。	// @contact.email [email protected]
license.name	必填 用于API的许可证名称。	// @license.name Apache 2.0
license.url	用于API的许可证的URL。 必须采用网址格式。	// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
host	运行API的主机（主机名或IP地址）。	// @host localhost:8080
BasePath	运行API的基本路径。	// @BasePath /api/v1
accept	API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的 *** 作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。	// @accept json
produce	API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。	// @produce json
query.collection.format	请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。 如果未设置，则默认为csv。	// @query.collection.format multi
schemes	用空格分隔的请求的传输协议。	// @schemes http https
x-name	扩展的键必须以x-开头，并且只能使用json值	// @x-example-key {“key”: “value”}

通用api信息，部分可以是在docs包里生成的，可以在项目启动的时候，或者在注册swagger路由的时候，修改掉部分信息，或者动态注入部分不固定的值，比如项目的基础路径：BasePath

func NewRouter() *gin.Engine {
	gin.SetMode("debug")
	engine := gin.New()
	docs.SwaggerInfo.BasePath = "/api/v2"
	engine.POST("/", v1.GetWord)
	engine.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	engine.GET("/log/:id", client.ReadLokiLog)
	return engine
}

每个API的注释编写-单个api

注释	描述
description	*** 作行为的详细说明。
description.markdown	应用程序的简短描述。该描述将从名为endpointname.md的文件中读取。
id	用于标识 *** 作的唯一字符串。在所有API *** 作中必须唯一。
tags	每个API *** 作的标签列表，以逗号分隔。
summary	该 *** 作的简短摘要。
accept	API 可以使用的 MIME 类型列表。 请注意，Accept 仅影响具有请求正文的 *** 作，例如 POST、PUT 和 PATCH。 值必须如“Mime类型”中所述。
produce	API可以生成的MIME类型的列表。值必须如“Mime类型”中所述。
param	用空格分隔的参数。param name,param type,data type,is mandatory?,comment attribute(optional)
security	每个API *** 作的安全性。
success	以空格分隔的成功响应。return code,{param type},data type,comment
failure	以空格分隔的故障响应。return code,{param type},data type,comment
response	与success、failure作用相同
header	以空格分隔的头字段。 return code,{param type},data type,comment
router	以空格分隔的路径定义。 path,[httpMethod]
x-name	扩展字段必须以x-开头，并且只能使用json值。

// @Summary 测试swagger
// @Tags test
// @version 1.0
// @Success 200 object FinalResult{data=v1.Application} 成功后返回值
// @Failure 500 object FinalResult 添加失败
// @Router / [get]
func GetWord(ctx *gin.Context) {
	application := &Application{Id: 1}
	err := ctx.BindJSON(application)
	if err != nil {
		ctx.JSON(500, "")
	}

	ctx.JSON(200, SuccessResult(application))
}

summary 是这个api的名字，可以显示在yapi的名称
tag 是这个api所在的分组
success 支持组合嵌套
param 说明了api需要的请求参数
param的类型支持：

querypathheaderbodyformData 需要对返回参数或者请求参数增加说明描述

直接在参数属性后面增加注释，也可以指定参数的名称说明描述

type Application struct {
	Id   int    `json:"id" example:"2"`     // 环境ID
	Name string `json:"name" example:"环境一"` // Name 环境名称
}

忽略某个字段：

type Account struct {
    ID   string    `json:"id"`
    Name string     `json:"name"`
    Ignored int     `swaggerignore:"true"`
}