注释 描述 参数 示例
securitydefinitions.basic Basic auth. // @securityDefinitions.basic BasicAuth
securitydefinitions.apikey API key auth. in, name // @securityDefinitions.apikey ApiKeyAuth
securitydefinitions.oauth2.application OAuth2 application auth. tokenUrl, scope // @securitydefinitions.oauth2.application OAuth2Application
securitydefinitions.oauth2.implicit OAuth2 implicit auth. authorizationUrl, scope // @securitydefinitions.oauth2.implicit OAuth2Implicit
securitydefinitions.oauth2.password OAuth2 password auth. tokenUrl, scope // @securitydefinitions.oauth2.password OAuth2Password
securitydefinitions.oauth2.accessCode OAuth2 access code auth. tokenUrl, authorizationUrl, scope // @securitydefinitions.oauth2.accessCode OAuth2AccessCode
参数注释 示例
in // @in header
name // @name Authorization
tokenUrl // @tokenUrl https://example.com/oauth/token
authorizationurl // @authorizationurl https://example.com/oauth/authorize
scope.hoge // @scope.write Grants write access

属性

// @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"          minimum(1)    maximum(10)
// @Param   default     query     string     false  "string default"     default(A)
// @Param   collection  query     []string   false  "string collection"  collectionFormat(multi)
// @Param   extensions  query     []string   false  "string collection"  extensions(x-example=test,x-nullable)

也适用于结构体字段：

type Foo struct {
    Bar string `minLength:"4" maxLength:"16"`
    Baz int `minimum:"10" maximum:"20" default:"15"`
    Qux []string `enums:"foo,bar,baz"`
}

当前可用的

字段名 类型 描述
default * 声明如果未提供任何参数，则服务器将使用的默认参数值，例如，如果请求中的客户端未提供该参数，则用于控制每页结果数的“计数”可能默认为100。 （注意：“default”对于必需的参数没有意义）。参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2。 与JSON模式不同，此值务必符合此参数的定义类型。
maximum number 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.2.
minimum number 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.3.
maxLength integer 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.1.
minLength integer 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.2.
enums [*] 参看 https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1.
format string 上面提到的类型的扩展格式。有关更多详细信息，请参见数据类型格式。
collectionFormat string 指定query数组参数的格式。 可能的值为：
  • csv - 逗号分隔值 foo,bar.
  • ssv - 空格分隔值 foo bar.
  • tsv - 制表符分隔值 foo\tbar.
  • pipes - 管道符分隔值 foo|bar.
  • multi - 对应于多个参数实例，而不是单个实例 foo=bar＆foo=baz 的多个值。这仅对“query”或“formData”中的参数有效。
默认值是 csv。

进一步的

字段名 类型 描述
multipleOf number See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.
pattern string See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
maxItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.
minItems integer See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.
uniqueItems boolean See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.
最后编辑: kuteng  文档更新时间: 2022-01-19 11:54   作者：kuteng