Go项目快速集成Swagger UI

本是古典何须时尚 2024-02-05 16:58 6阅读 0赞

## swag ##

Swag将Go的注释转换为Swagger2.0文档。我们为流行的 Go Web Framework 创建了各种插件，这样可以与现有Go项目快速集成（使用Swagger UI）。

### 目录 ###

*  快速开始
 *  支持的Web框架
 *  如何与Gin集成
 *  格式化说明
 *  开发现状
 *  声明式注释格式
    
     *  通用API信息
     *  API操作
     *  安全性
 *  样例
    
     *  多行的描述
     *  用户自定义的具有数组类型的结构
     *  响应对象中的模型组合
     *  在响应中增加头字段
     *  使用多路径参数
     *  结构体的示例值
     *  结构体描述
     *  使用`swaggertype`标签更改字段类型
     *  使用`swaggerignore`标签排除字段
     *  将扩展信息添加到结构字段
     *  对展示的模型重命名
     *  如何使用安全性注释
 *  项目相关

### 快速开始 ###

1.  将注释添加到API源代码中，请参阅声明性注释格式。
2.  使用如下命令下载swag：

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

从源码开始构建的话，需要有Go环境（1.18及以上版本）。

或者从github的release页面下载预编译好的二进制文件。

1.  在包含`main.go`文件的项目根目录运行`swag init`。这将会解析注释并生成需要的文件（`docs`文件夹和`docs/docs.go`）。

swag init

确保导入了生成的`docs/docs.go`文件，这样特定的配置文件才会被初始化。如果通用API注释没有写在`main.go`中，可以使用`-g`标识符来告知swag。

swag init -g http/api.go

1.  (可选) 使用`fmt`格式化 SWAG 注释。(请先升级到最新版本)

swag fmt

### swag cli ###

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")

swag fmt -h
    NAME:
       swag fmt - format swag comments
    
    USAGE:
       swag fmt [command options] [arguments...]
    
    OPTIONS:
       --dir value, -d value          API解析目录 (默认: "./")
       --exclude value                解析扫描时排除的目录，多个目录可用逗号分隔（默认：空）
       --generalInfo value, -g value  API通用信息所在的go源文件路径，如果是相对路径则基于API解析目录 (默认: "main.go")
       --help, -h                     show help (default: false)

### 支持的Web框架 ###

*  [gin][]
 *  [echo][]
 *  [buffalo][]
 *  [net/http][net_http]
 *  [gorilla/mux][net_http]
 *  [go-chi/chi][net_http]
 *  [flamingo][]
 *  [fiber][]
 *  [atreugo][]
 *  [hertz][]

### 如何与Gin集成 ###

[点击此处][Link 1]查看示例源代码。

1.  使用`swag init`生成Swagger2.0文档后，导入如下代码包：

import "github.com/swaggo/gin-swagger" // gin-swagger middleware
    import "github.com/swaggo/files" // swagger embed files

1.  在`main.go`源代码中添加通用的API注释：

// @title           Swagger Example API
    // @version         1.0
    // @description     This is a sample server celler server.
    // @termsOfService  http://swagger.io/terms/
    
    // @contact.name   API Support
    // @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      localhost:8080
    // @BasePath  /api/v1
    
    // @securityDefinitions.basic  BasicAuth
    
    // @externalDocs.description  OpenAPI
    // @externalDocs.url          https://swagger.io/resources/open-api/
    func main() {
        
        r := gin.Default()
    
        c := controller.NewController()
    
        v1 := r.Group("/api/v1")
        {
        
            accounts := v1.Group("/accounts")
            {
        
                accounts.GET(":id", c.ShowAccount)
                accounts.GET("", c.ListAccounts)
                accounts.POST("", c.AddAccount)
                accounts.DELETE(":id", c.DeleteAccount)
                accounts.PATCH(":id", c.UpdateAccount)
                accounts.POST(":id/images", c.UploadAccountImage)
            }
        //...
        }
        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
        r.Run(":8080")
    }
    //...

此外，可以动态设置一些通用的API信息。生成的代码包`docs`导出`SwaggerInfo`变量，使用该变量可以通过编码的方式设置标题、描述、版本、主机和基础路径。使用Gin的示例：

package main
    
    import (
        "github.com/gin-gonic/gin"
        "github.com/swaggo/files"
        "github.com/swaggo/gin-swagger"
    
        "./docs" // docs is generated by Swag CLI, you have to import it.
    )
    
    // @contact.name   API Support
    // @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
    func main() {
        
    
        // programatically set swagger info
        docs.SwaggerInfo.Title = "Swagger Example API"
        docs.SwaggerInfo.Description = "This is a sample server Petstore server."
        docs.SwaggerInfo.Version = "1.0"
        docs.SwaggerInfo.Host = "petstore.swagger.io"
        docs.SwaggerInfo.BasePath = "/v2"
        docs.SwaggerInfo.Schemes = []string{
        "http", "https"}
    
        r := gin.New()
    
        // use ginSwagger middleware to serve the API docs
        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
    
        r.Run()
    }

1.  在`controller`代码中添加API操作注释：

package controller
    
    import (
        "fmt"
        "net/http"
        "strconv"
    
        "github.com/gin-gonic/gin"
        "github.com/swaggo/swag/example/celler/httputil"
        "github.com/swaggo/swag/example/celler/model"
    )
    
    // ShowAccount godoc
    // @Summary      Show an account
    // @Description  get string by ID
    // @Tags         accounts
    // @Accept       json
    // @Produce      json
    // @Param        id   path      int  true  "Account ID"
    // @Success      200  {object}  model.Account
    // @Failure      400  {object}  httputil.HTTPError
    // @Failure      404  {object}  httputil.HTTPError
    // @Failure      500  {object}  httputil.HTTPError
    // @Router       /accounts/{id} [get]
    func (c *Controller) ShowAccount(ctx *gin.Context) {
        
      id := ctx.Param("id")
      aid, err := strconv.Atoi(id)
      if err != nil {
        
        httputil.NewError(ctx, http.StatusBadRequest, err)
        return
      }
      account, err := model.AccountOne(aid)
      if err != nil {
        
        httputil.NewError(ctx, http.StatusNotFound, err)
        return
      }
      ctx.JSON(http.StatusOK, account)
    }
    
    // ListAccounts godoc
    // @Summary      List accounts
    // @Description  get accounts
    // @Tags         accounts
    // @Accept       json
    // @Produce      json
    // @Param        q    query     string  false  "name search by q"  Format(email)
    // @Success      200  {array}   model.Account
    // @Failure      400  {object}  httputil.HTTPError
    // @Failure      404  {object}  httputil.HTTPError
    // @Failure      500  {object}  httputil.HTTPError
    // @Router       /accounts [get]
    func (c *Controller) ListAccounts(ctx *gin.Context) {
        
      q := ctx.Request.URL.Query().Get("q")
      accounts, err := model.AccountsAll(q)
      if err != nil {
        
        httputil.NewError(ctx, http.StatusNotFound, err)
        return
      }
      ctx.JSON(http.StatusOK, accounts)
    }
    //...

swag init

1.  运行程序，然后在浏览器中访问 http://localhost:8080/swagger/index.html 。将看到Swagger 2.0 Api文档，如下所示：

![swagger\_index.html][swagger_index.html]

### 格式化说明 ###

可以针对Swag的注释自动格式化，就像`go fmt`。  
此处查看格式化结果 [here][Link 1].

示例：

swag fmt

排除目录（不扫描）示例：

swag fmt -d ./ --exclude ./internal

### 开发现状 ###

[Swagger 2.0 文档][Swagger 2.0]

*  Basic Structure
 *  API Host and Base Path
 *  Paths and Operations
 *  Describing Parameters
 *  Describing Request Body
 *  Describing Responses
 *  MIME Types
 *  Authentication
    
     *  Basic Authentication
     *  API Keys
 *  Adding Examples
 *  File Upload
 *  Enums
 *  Grouping Operations With Tags
 *  Swagger Extensions

### 声明式注释格式 ###

### 通用API信息 ###

**示例** [`celler/main.go`][celler_main.go]

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

#### 使用Markdown描述 ####

如果文档中的短字符串不足以完整表达，或者需要展示图片，代码示例等类似的内容，则可能需要使用Markdown描述。要使用Markdown描述，请使用一下注释。

### API操作 ###

Example [celler/controller][celler_controller]

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

### Mime类型 ###

`swag` 接受所有格式正确的MIME类型, 即使匹配 `*/*`。除此之外，`swag`还接受某些MIME类型的别名，如下所示：

<table> 
 <thead> 
  <tr> 
   <th>Alias</th> 
   <th>MIME Type</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>json</td> 
   <td>application/json</td> 
  </tr> 
  <tr> 
   <td>xml</td> 
   <td>text/xml</td> 
  </tr> 
  <tr> 
   <td>plain</td> 
   <td>text/plain</td> 
  </tr> 
  <tr> 
   <td>html</td> 
   <td>text/html</td> 
  </tr> 
  <tr> 
   <td>mpfd</td> 
   <td>multipart/form-data</td> 
  </tr> 
  <tr> 
   <td>x-www-form-urlencoded</td> 
   <td>application/x-www-form-urlencoded</td> 
  </tr> 
  <tr> 
   <td>json-api</td> 
   <td>application/vnd.api+json</td> 
  </tr> 
  <tr> 
   <td>json-stream</td> 
   <td>application/x-json-stream</td> 
  </tr> 
  <tr> 
   <td>octet-stream</td> 
   <td>application/octet-stream</td> 
  </tr> 
  <tr> 
   <td>png</td> 
   <td>image/png</td> 
  </tr> 
  <tr> 
   <td>jpeg</td> 
   <td>image/jpeg</td> 
  </tr> 
  <tr> 
   <td>gif</td> 
   <td>image/gif</td> 
  </tr> 
 </tbody> 
</table>

### 参数类型 ###

*  query
 *  path
 *  header
 *  body
 *  formData

### 数据类型 ###

*  string (string)
 *  integer (int, uint, uint32, uint64)
 *  number (float32)
 *  boolean (bool)
 *  user defined struct

### 安全性 ###

<table> 
 <thead> 
  <tr> 
   <th>注释</th> 
   <th>描述</th> 
   <th>参数</th> 
   <th>示例</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>securitydefinitions.basic</td> 
   <td><a href="https://swagger.io/docs/specification/2-0/authentication/basic-authentication/" rel="nofollow">Basic</a> auth.</td> 
   <td></td> 
   <td>// @securityDefinitions.basic BasicAuth</td> 
  </tr> 
  <tr> 
   <td>securitydefinitions.apikey</td> 
   <td><a href="https://swagger.io/docs/specification/2-0/authentication/api-keys/" rel="nofollow">API key</a> auth.</td> 
   <td>in, name</td> 
   <td>// @securityDefinitions.apikey ApiKeyAuth</td> 
  </tr> 
  <tr> 
   <td>securitydefinitions.oauth2.application</td> 
   <td><a href="https://swagger.io/docs/specification/authentication/oauth2/" rel="nofollow">OAuth2 application</a> auth.</td> 
   <td>tokenUrl, scope</td> 
   <td>// @securitydefinitions.oauth2.application OAuth2Application</td> 
  </tr> 
  <tr> 
   <td>securitydefinitions.oauth2.implicit</td> 
   <td><a href="https://swagger.io/docs/specification/authentication/oauth2/" rel="nofollow">OAuth2 implicit</a> auth.</td> 
   <td>authorizationUrl, scope</td> 
   <td>// @securitydefinitions.oauth2.implicit OAuth2Implicit</td> 
  </tr> 
  <tr> 
   <td>securitydefinitions.oauth2.password</td> 
   <td><a href="https://swagger.io/docs/specification/authentication/oauth2/" rel="nofollow">OAuth2 password</a> auth.</td> 
   <td>tokenUrl, scope</td> 
   <td>// @securitydefinitions.oauth2.password OAuth2Password</td> 
  </tr> 
  <tr> 
   <td>securitydefinitions.oauth2.accessCode</td> 
   <td><a href="https://swagger.io/docs/specification/authentication/oauth2/" rel="nofollow">OAuth2 access code</a> auth.</td> 
   <td>tokenUrl, authorizationUrl, scope</td> 
   <td>// @securitydefinitions.oauth2.accessCode OAuth2AccessCode</td> 
  </tr> 
 </tbody> 
</table>

<table> 
 <thead> 
  <tr> 
   <th>参数注释</th> 
   <th>示例</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>in</td> 
   <td>// @in header</td> 
  </tr> 
  <tr> 
   <td>name</td> 
   <td>// @name Authorization</td> 
  </tr> 
  <tr> 
   <td>tokenUrl</td> 
   <td>// @tokenUrl https://example.com/oauth/token</td> 
  </tr> 
  <tr> 
   <td>authorizationurl</td> 
   <td>// @authorizationurl https://example.com/oauth/authorize</td> 
  </tr> 
  <tr> 
   <td>scope.hoge</td> 
   <td>// @scope.write Grants write access</td> 
  </tr> 
 </tbody> 
</table>

### 属性 ###

// @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"`
    }

#### 当前可用的 ####

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

#### 进一步的 ####

<table> 
 <thead> 
  <tr> 
   <th>字段名</th> 
   <th align="center">类型</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>multipleOf</td> 
   <td align="center"><code>number</code></td> 
   <td>See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.1.1.</td> 
  </tr> 
  <tr> 
   <td>pattern</td> 
   <td align="center"><code>string</code></td> 
   <td>See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.</td> 
  </tr> 
  <tr> 
   <td>maxItems</td> 
   <td align="center"><code>integer</code></td> 
   <td>See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.2.</td> 
  </tr> 
  <tr> 
   <td>minItems</td> 
   <td align="center"><code>integer</code></td> 
   <td>See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.3.</td> 
  </tr> 
  <tr> 
   <td>uniqueItems</td> 
   <td align="center"><code>boolean</code></td> 
   <td>See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.3.4.</td> 
  </tr> 
 </tbody> 
</table>

### 样例 ###

#### 多行的描述 ####

可以在常规api描述或路由定义中添加跨越多行的描述，如下所示：

// @description This is the first line
    // @description This is the second line
    // @description And so forth.

#### 用户自定义的具有数组类型的结构 ####

// @Success 200 {array} model.Account <-- This is a user defined struct.

package model
    
    type Account struct {
        
        ID   int    `json:"id" example:"1"`
        Name string `json:"name" example:"account name"`
    }

#### 响应对象中的模型组合 ####

// JSONResult的data字段类型将被proto.Order类型替换
    @success 200 {
        object} jsonresult.JSONResult{
        data=proto.Order} "desc"

type JSONResult struct {
        
        Code    int          `json:"code" `
        Message string       `json:"message"`
        Data    interface{
        }  `json:"data"`
    }
    
    type Order struct {
         //in `proto` package
        ...
    }

*  还支持对象数组和原始类型作为嵌套响应

@success 200 {
        object} jsonresult.JSONResult{
        data=[]proto.Order} "desc"
    @success 200 {
        object} jsonresult.JSONResult{
        data=string} "desc"
    @success 200 {
        object} jsonresult.JSONResult{
        data=[]string} "desc"

*  替换多个字段的类型。如果某字段不存在，将添加该字段。

@success 200 {
        object} jsonresult.JSONResult{
        data1=string,data2=[]string,data3=proto.Order,data4=[]proto.Order} "desc"

#### 在响应中增加头字段 ####

// @Success      200              {string}  string    "ok"
    // @failure      400              {string}  string    "error"
    // @response     default          {string}  string    "other error"
    // @Header       200              {string}  Location  "/entity/1"
    // @Header       200,400,default  {string}  Token     "token"
    // @Header       all              {string}  Token2    "token2"

#### 使用多路径参数 ####

/// ...
    // @Param  group_id    path  int  true  "Group ID"
    // @Param  account_id  path  int  true  "Account ID"
    // ...
    // @Router /examples/groups/{group_id}/accounts/{account_id} [get]

#### 结构体的示例值 ####

type Account struct {
        
        ID   int    `json:"id" example:"1"`
        Name string `json:"name" example:"account name"`
        PhotoUrls []string `json:"photo_urls" example:"http://test/image/1.jpg,http://test/image/2.jpg"`
    }

#### 结构体描述 ####

type Account struct {
        
        // ID this is userid
        ID   int    `json:"id"`
        Name string `json:"name"` // This is Name
    }

#### 使用`swaggertype`标签更改字段类型 ####

[\#201][201]

type TimestampTime struct {
        
        time.Time
    }
    
    ///实现encoding.JSON.Marshaler接口
    func (t *TimestampTime) MarshalJSON() ([]byte, error) {
        
        bin := make([]byte, 16)
        bin = strconv.AppendInt(bin[:0], t.Time.Unix(), 10)
        return bin, nil
    }
    
    ///实现encoding.JSON.Unmarshaler接口
    func (t *TimestampTime) UnmarshalJSON(bin []byte) error {
        
        v, err := strconv.ParseInt(string(bin), 10, 64)
        if err != nil {
        
            return err
        }
        t.Time = time.Unix(v, 0)
        return nil
    }
    ///
    
    type Account struct {
        
        // 使用`swaggertype`标签将别名类型更改为内置类型integer
        ID     sql.NullInt64 `json:"id" swaggertype:"integer"`
    
        // 使用`swaggertype`标签更改struct类型为内置类型integer
        RegisterTime TimestampTime `json:"register_time" swaggertype:"primitive,integer"`
    
        // Array types can be overridden using "array,<prim_type>" format
        Coeffs []big.Float `json:"coeffs" swaggertype:"array,number"`
    }

[\#379][379]

type CerticateKeyPair struct {
        
        Crt []byte `json:"crt" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
        Key []byte `json:"key" swaggertype:"string" format:"base64" example:"U3dhZ2dlciByb2Nrcw=="`
    }

生成的swagger文档如下：

"api.MyBinding": {
        
      "type":"object",
      "properties":{
        
        "crt":{
        
          "type":"string",
          "format":"base64",
          "example":"U3dhZ2dlciByb2Nrcw=="
        },
        "key":{
        
          "type":"string",
          "format":"base64",
          "example":"U3dhZ2dlciByb2Nrcw=="
        }
      }
    }

#### 使用`swaggerignore`标签排除字段 ####

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

#### 将扩展信息添加到结构字段 ####

type Account struct {
        
        ID   string    `json:"id"   extensions:"x-nullable,x-abc=def,!x-omitempty"` // 扩展字段必须以"x-"开头
    }

生成swagger文档，如下所示：

"Account": {
        
        "type": "object",
        "properties": {
        
            "id": {
        
                "type": "string",
                "x-nullable": true,
                "x-abc": "def",
                "x-omitempty": false
            }
        }
    }

#### 对展示的模型重命名 ####

type Resp struct {
        
        Code int
    }//@name Response

#### 如何使用安全性注释 ####

通用API信息。

// @securityDefinitions.basic BasicAuth
    
    // @securitydefinitions.oauth2.application OAuth2Application
    // @tokenUrl https://example.com/oauth/token
    // @scope.write Grants write access
    // @scope.admin Grants read and write access to administrative information

每个API操作。

// @Security ApiKeyAuth

使用AND条件。

// @Security ApiKeyAuth
    // @Security OAuth2Application[write, admin]

[gin]: http://github.com/swaggo/gin-swagger
[echo]: http://github.com/swaggo/echo-swagger
[buffalo]: https://github.com/swaggo/buffalo-swagger
[net_http]: https://github.com/swaggo/http-swagger
[flamingo]: https://github.com/i-love-flamingo/swagger
[fiber]: https://github.com/gofiber/swagger
[atreugo]: https://github.com/Nerzal/atreugo-swagger
[hertz]: https://github.com/hertz-contrib/swagger
[Link 1]: https://github.com/swaggo/swag/tree/master/example/celler
[swagger_index.html]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/30/4130691c27524e1c91ac593356af0fb5.png
[Swagger 2.0]: https://swagger.io/docs/specification/2-0/basic-structure/
[celler_main.go]: https://github.com/swaggo/swag/blob/master/example/celler/main.go
[celler_controller]: https://github.com/swaggo/swag/tree/master/example/celler/controller
[201]: https://github.com/swaggo/swag/issues/201#issuecomment-475479409
[379]: https://github.com/swaggo/swag/issues/379