字数 2895，阅读大约需 15 分钟

分享我在Gin里使用Swag生成API文档，提效开发

摘要

本文旨在介绍如何在Gin里生成API文档，哈哈(≧ω≦)；分享我在使用Gin的时候，将代码转为API，然后演示在Swagger浏览器页面或者是apifox里调用代码里的业务API；

定义

Swagger（现在叫OpenAPI）

1. 是一套规范标准，定义了如何描述RESTful API
2. 提供了可视化的API文档界面，让开发者可以直接在网页上测试API
3. 输出格式：swagger.json 或 swagger.yaml 文件
4. 语言无关，几乎所有主流编程语言都有支持工具

Swag

1. 专门为Go语言开发的工具
2. 通过解析Go代码中的特殊注释自动生成Swagger文档
3. 主要命令：swag init 生成docs文件夹和相关文档文件
4. 代码中添加类似 // @Summary // @Description 这样的注释

Swagger

1. gin框架的中间件
2. swag生成的文档集成到Gin应用中
3. 提供了 /swagger/index.html 这样的路由来访问文档页面
4. 让用户可以直接在浏览器中查看和测试API

开发演示

mian.go

对应的字段含义，可在官方文档或者AI查询到使用说明，建议在开发的时候多查查，通过实践锻炼理解文档；

package main

import (
    swaggerFiles "github.com/swaggo/files"     // swagger embed files
    ginSwagger "github.com/swaggo/gin-swagger" // gin-swagger middleware
)

// 程序入口
// @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  [email protected]

// @license.name  Apache 2.0
// @license.url   http://www.apache.org/licenses/LICENSE-2.0.html

// @host      localhost:8992
// @BasePath  /api/v1/gin

// @securityDefinitions.basic  BasicAuth

// @externalDocs.description  OpenAPI
// @externalDocs.url          https://swagger.io/resources/open-api/

api代码里

// 创建服务工单
// ShowAccount godoc
// @Summary      create a workorder
// @Description  get string by ID
// @Tags         WorkOrder
// @Accept       json
// @Produce      json
// @Param data body schema.WorkOrderCreate true "工单"
// @Router       /workorder/ [post]
func CreateWorkOrder(c *gin.Context) {
}

swagger

官方文档

swag/README_zh-CN.md at master · swaggo/swag^[1]

快速开始

中文文档^[2]

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

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

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

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

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

swag init

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

swag init -g http/api.go

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

swag fmt

swag cli

^[3]

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源文件，默认不
   --parseDependencyLevel, --pdl          对'--parseDependency'参数进行增强, 是否解析依赖目录中的go源文件, 0 不解析, 1 只解析对象模型, 2 只解析API, 3 对象模型和API都解析 (default: 0)
   --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)

如何与Gin集成

^[4]

点击此处^[5]查看示例源代码。

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

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

2. 在 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  [email protected]

// @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  [email protected]

// @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()
}

3. 在 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

http://localhost:8992/swagger/index.html#/

详细声明注释格式

swag/README_zh-CN.md at master · swaggo/swag^[6]

mian.go

注释	说明	示例
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.urlhttps://example.com^[7]
tag.docs.description	标签的外部文档说明。	// @tag.docs.description Best example documentation
termsOfService	API的服务条款。	// @termsOfServicehttp://swagger.io/terms/
contact.name	公开的API的联系信息。	// @contact.name API Support
contact.url	联系信息的URL。必须采用网址格式。	// @contact.urlhttp://www.swagger.io/support
contact.email	联系人/组织的电子邮件地址。必须采用电子邮件地址的格式。	// @contact.email[email protected]^[8]
license.name	必填用于API的许可证名称。	// @license.name Apache 2.0
license.url	用于API的许可证的URL。必须采用网址格式。	// @license.urlhttp://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类型^[9]”中所述。	// @accept json
produce	API可以生成的MIME类型的列表。值必须如“Mime类型^[10]”中所述。	// @produce json
query.collection.format	请求URI query里数组参数的默认格式：csv，multi，pipes，tsv，ssv。如果未设置，则默认为csv。	// @query.collection.format multi
schemes	用空格分隔的请求的传输协议。	// @schemes http https
externalDocs.description	Description of the external document.	// @externalDocs.description OpenAPI
externalDocs.url	URL of the external document.	// @externalDocs.urlhttps://swagger.io/resources/open-api/
x-name	扩展的键必须以x-开头，并且只能使用json值	// @x-example-key {"key": "value"}

api.go

注释	描述
description	操作行为的详细说明。
description.markdown	应用程序的简短描述。该描述将从名为 `endpointname.md`的文件中读取。
id	用于标识操作的唯一字符串。在所有API操作中必须唯一。
tags	每个API操作的标签列表，以逗号分隔。
summary	该操作的简短摘要。
accept	API 可以使用的 MIME 类型列表。请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。值必须如“Mime类型^[11]”中所述。
produce	API可以生成的MIME类型的列表。值必须如“Mime类型^[12]”中所述。
param	用空格分隔的参数。`param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)`
security	每个API操作的安全性^[13]。
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]`
deprecatedrouter	与router相同，但是是deprecated的。
x-name	扩展字段必须以 `x-`开头，并且只能使用json值。
deprecated	将当前API操作的所有路径设置为deprecated

注释	描述
description	操作行为的详细说明。
description.markdown	应用程序的简短描述。该描述将从名为 `endpointname.md`的文件中读取。
id	用于标识操作的唯一字符串。在所有API操作中必须唯一。
tags	每个API操作的标签列表，以逗号分隔。
summary	该操作的简短摘要。
accept	API 可以使用的 MIME 类型列表。请注意，Accept 仅影响具有请求正文的操作，例如 POST、PUT 和 PATCH。值必须如“Mime类型^[14]”中所述。
produce	API可以生成的MIME类型的列表。值必须如“Mime类型^[15]”中所述。
param	用空格分隔的参数。`param name`,`param type`,`data type`,`is mandatory?`,`comment` `attribute(optional)`
security	每个API操作的安全性^[16]。
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]`
deprecatedrouter	与router相同，但是是deprecated的。
x-name	扩展字段必须以 `x-`开头，并且只能使用json值。
deprecated	将当前API操作的所有路径设置为deprecated

mime

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

参数类型

^[17]

• query
• path
• header
• body
• formData

数据类型

^[18]

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

More: 见官方文档：swag/README_zh-CN.md at master · swaggo/swag^[19]

引用链接

[1] swag/README_zh-CN.md at master · swaggo/swag: https://github.com/swaggo/swag/blob/master/README_zh-CN.md
[2] 中文文档: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#%E5%BF%AB%E9%80%9F%E5%BC%80%E5%A7%8B
[3] : https://github.com/swaggo/swag/blob/master/README_zh-CN.md#swag-cli
[4] : https://github.com/swaggo/swag/blob/master/README_zh-CN.md#%E5%A6%82%E4%BD%95%E4%B8%8Egin%E9%9B%86%E6%88%90
[5] 点击此处: https://github.com/swaggo/swag/tree/master/example/celler
[6] swag/README_zh-CN.md at master · swaggo/swag: https://github.com/swaggo/swag/blob/master/README_zh-CN.md
[7] https://example.com: https://example.com/
[8] [email protected]: mailto:[email protected]
[9] Mime类型: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#mime%E7%B1%BB%E5%9E%8B
[10] Mime类型: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#mime%E7%B1%BB%E5%9E%8B
[11] Mime类型: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#mime%E7%B1%BB%E5%9E%8B
[12] Mime类型: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#mime%E7%B1%BB%E5%9E%8B
[13] 安全性: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#%E5%AE%89%E5%85%A8%E6%80%A7
[14] Mime类型: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#mime%E7%B1%BB%E5%9E%8B
[15] Mime类型: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#mime%E7%B1%BB%E5%9E%8B
[16] 安全性: https://github.com/swaggo/swag/blob/master/README_zh-CN.md#%E5%AE%89%E5%85%A8%E6%80%A7
[17] : https://github.com/swaggo/swag/blob/master/README_zh-CN.md#%E5%8F%82%E6%95%B0%E7%B1%BB%E5%9E%8B
[18] : https://github.com/swaggo/swag/blob/master/README_zh-CN.md#%E6%95%B0%E6%8D%AE%E7%B1%BB%E5%9E%8B
[19] swag/README_zh-CN.md at master · swaggo/swag: https://github.com/swaggo/swag/blob/master/README_zh-CN.md

目录CONTENT

分享我在Gin里使用Swag生成API文档，提效开发

分享我在Gin里使用Swag生成API文档，提效开发

摘要

定义

Swagger（现在叫OpenAPI）

Swag

Swagger

开发演示

mian.go

api代码里

swagger

官方文档

快速开始

swag cli

如何与Gin集成

详细声明注释格式

mian.go

api.go

mime

参数类型

数据类型

引用链接

评论区