使用swaggo自动生成restful API文档

我相信很多程序猿，像我一样，不喜欢编写API文档。写代码是多么舒服。写文档不仅要花很多时间，有时还不够全面。但API文档是必不可少的。我不需要说我相信他们很重要。一份含糊不清的文件甚至会引起前后人员的争斗。今天的博客中介绍的Swaggo是一个工具，它允许您只需关注代码就可以生成完美的API文档。有很多废话。让我们直接读这篇文章。

最终文件效果可能如下所示：

1.1.1. 关于斯瓦戈

1.1.1. 关于Swaggo

或许你使用过Swagger, 而 swaggo就是代替了你手动编写yaml的部分。只要通过一个命令就可以将注释转换成文档，这让我们可以更加专注于代码。

目前swaggo主要实现了swagger 2.0 的以下部分功能：

  • 基本结构（Basic Structure）

  • API 地址与基本路径（API Host and Base Path）

  • 路径与操作 （Paths and Operations）

  • 参数描述（Describing Parameters）

  • 请求参数描述（Describing Request Body）

  • 返回描述（Describing Responses）

  • MIME 类型（MIME Types）

  • 认证（Authentication）

    • Basic Authentication

    • API Keys

  • 添加实例（Adding Examples）

  • 文件上传（File Upload）

  • 枚举（Enums）

  • 按标签分组（Grouping Operations With Tags）

  • 扩展（Swagger Extensions）

下文内容均以gin-swaggo为例 这里是demo地址

1.1.2. 使用

安装swag cli 及下载相关包

要使用swaggo,首先需要安装swag cli。

   go get -u github.com/swaggo/swag/cmd/swag

然后我们还需要两个包。

# gin-swagger 中间件
go get github.com/swaggo/gin-swagger
# swagger 内置文件
go get github.com/swaggo/gin-swagger/swaggerFiles

在main.go内添加注释

如上所示，我们需要导入

ginSwagger "github.com/swaggo/gin-swagger"
"github.com/swaggo/gin-swagger/swaggerFiles"

同时，添加注释。其中：

  • titile: 文档标题

  • version: 版本

  • description,termsOfService,contact ... 这些都是一些声明，可不写。

  • license.name 额，这个是必须的。

  • host,BasePath: 如果你想直接swagger调试API，这两项需要填写正确。前者为服务文档的端口，ip。后者为基础路径，像我这里就是“/api/v1”。

  • 在原文档中还有securityDefinitions.basic,securityDefinitions.apikey等，这些都是用来做认证的，我这里暂不展开。

到这里，我们在mian.go同目录下执行swag init就可以自动生成文档，如下：

E:\goproject\src\github.com\topgoer>swag init
2020/05/13 16:28:02 Generate swagger docs....
2020/05/13 16:28:02 Generate general API Info, search dir:./
2020/05/13 16:28:02 create docs.go at  docs/docs.go
2020/05/13 16:28:02 create swagger.json at  docs/swagger.json
2020/05/13 16:28:02 create swagger.yaml at  docs/swagger.yaml

然后我们在main.go导入这个自动生成的docs包，运行：

package mainimport (
   "github.com/gin-gonic/gin"
   ginSwagger "github.com/swaggo/gin-swagger"
   "github.com/swaggo/gin-swagger/swaggerFiles"

   _ "github.com/razeencheng/demo-go/swaggo-gin/docs")// @title Swagger Example API// @version 1.0// ...E:\goproject\src\github.com\topgoer>go run main.go
[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.

[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
- using env:   export GIN_MODE=release
- using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /swagger/*any             --> github.com/swaggo/gin-swagger.CustomWrapHandler.func1 (3 handlers)
[GIN-debug] GET    /api/v1/hello             --> main.HandleHello (3 handlers)
[GIN-debug] Listening and serving HTTP on :8080

1.1.3. 在Handle函数上添加注释

接下来，我们需要在每个路由处理函数上加上注释，如：

我们再次swag init, 运行一下。

此时，该API的相关描述已经生成了，我们点击Try it out还可以直接测试该API。

是不是很好用，当然这并没有结束，这些注释字段，我们一个个解释。

这些注释对应出现在API文档的位置，我在上图中已经标出，这里我们主要详细说说下面参数：

Tags

Tags 是用来给API分组的。

Accept

接收的参数类型，支持表单(mpfd) 和 JSON(json)

Produce

返回的数据结构，一般都是json, 其他支持如下表：

Mime Type声明application/jsonjsontext/xmlxmltext/plainplainhtmlhtmlmultipart/form-datampfdapplication/x-www-form-urlencodedx-www-form-urlencodedapplication/vnd.api+jsonjson-apiapplication/x-json-streamjson-streamapplication/octet-streamoctet-streamimage/pngpngimage/jpegjpegimage/gifgif

Param

参数，从前往后分别是：

@Param 1.参数名 2.参数类型 3.参数数据类型 4.是否必须 5.参数描述 6.其他属性

  • 1.参数名

    参数名就是我们解释参数的名字。

  • 2.参数类型

    参数类型主要有三种：

    • path 该类型参数直接拼接在URL中，如Demo中HandleGetFile：

      // @Param id path integer true "文件ID"

    • query 该类型参数一般是组合在URL中的，如Demo中HandleHello

      // @Param who query string true "人名"

    • formData 该类型参数一般是POST,PUT方法所用，如Demo中HandleLogin

      // @Param user formData string true "用户名" default(admin)

  • 3.参数数据类型

    数据类型主要支持一下几种：

    注意，如果你是上传文件可以使用file, 但参数类型一定是formData, 如下：

    // @Param file formData file true "文件"

    • string (string)

    • integer (int, uint, uint32, uint64)

    • number (float32)

    • boolean (bool)

  • 4.是否是必须

    表明该参数是否是必须需要的，必须的在文档中会黑体标出，测试时必须填写。

  • 5.参数描述

    就是参数的一些说明

  • 6.其他属性

    除了上面这些属性外，我们还可以为该参数填写一些额外的属性，如枚举，默认值，值范围等。如下：

    枚举
    // @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)

    而且这些参数是可以组合使用的，如：

    // @Param enumstring query string false "string enums" Enums(A, B, C) default(A)

    Success

指定成功响应的数据。格式为：

// @Success 1.HTTP响应码 {2.响应参数类型} 3.响应数据类型 4.其他描述

  • 1.HTTP响应码

    也就是200，400，500那些。

  • 2.响应参数类型 / 3.响应数据类型

    返回的数据类型，可以是自定义类型，可以是json。

    在平常的使用中，我都会返回一些指定的模型序列化JSON的数据，这时，就可以这么写：

    // @Success 200 {object} main.File

    其中，模型直接用包名.模型即可。你会说，假如我返回模型数组怎么办？这时你可以这么写：

    // @Success 200 {anrry} main.File

    将如你只是返回其他的json数据可如下写：

    // @Success 200 {string} json ""

    • json

    • 自定义类型

  • 4.其他描述

    可以添加一些说明。

Failure

同Success。

Router

指定路由与HTTP方法。格式为：

// @Router /path/to/handle [HTTP方法]

不用加基础路径哦。

1.1.4. 生成文档与测试

其实上面已经穿插的介绍了。

在main.go下运行swag init即可生成和更新文档。

点击文档中的Try it out即可测试。 如果部分API需要登陆，可以Try登陆接口即可。

1.1.5. 优化

看到这里，基本可以使用了。但文档一般只是我们测试的时候需要，当我的产品上线后，接口文档是不应该给用户的，而且带有接口文档的包也会大很多（swaggo是直接build到二进制里的）。

想要处理这种情况，我们可以在编译的时候优化一下，如利用build tag来控制是否编译文档。

在main.go声明swagHandler,并在该参数不为空时才加入路由：

package main//...var swagHandler gin.HandlerFuncfunc main(){
   // ...

       if swagHandler != nil {
           r.GET("/swagger/*any", swagHandler)
       }

   //...}

同时,我们将该参数在另外加了build tag的包中初始化。

// +build docpackage mainimport (
   _ "github.com/razeencheng/demo-go/swaggo-gin/docs"

   ginSwagger "github.com/swaggo/gin-swagger"
   "github.com/swaggo/gin-swagger/swaggerFiles")func init() {
   swagHandler = ginSwagger.WrapHandler(swaggerFiles.Handler)}

之后我们就可以使用go build -tags "doc"来打包带文档的包，直接go build来打包不带文档的包。

你会发现，即使我这么小的Demo,编译后的大小也要相差19M !

➜  swaggo-gin git:(master) ✗ go build
➜  swaggo-gin git:(master) ✗ ll swaggo-gin
-rwxr-xr-x  1 xxx  staff    15M Jan 13 00:23 swaggo-gin
➜  swaggo-gin git:(master) ✗ go build -tags "doc"
➜  swaggo-gin git:(master) ✗ ll swaggo-gin
-rwxr-xr-x  1 xxx  staff    34M Jan 13 00:24 swaggo-gin

文章到这里也就结束了，完整的Demo地址在这里。

相关链接

  • Swaggo Github

  • Swagger

资源下载：
下载地址： http://yemao.in/life?utm_source=sishubiji&utm_term=使用swaggo自动生成restful API文档