Golang使用swaggo自动生成Restful API文档

作者: 程序员khaos

关于Swaggo

相信很多程序猿和一样不喜欢写API文档。写代码多舒服,写文档不仅要花费大量的时间,有时候还不能做到面面具全。但API文档是必不可少的,相信其重要性就不用说了,一份含糊的文档甚至能让前后端人员打起来。 而今天这篇博客介绍的swaggo就是让你只需要专注于代码就可以生成完美API文档的工具。废话说的有点多,们直接看文章。

或许你使用过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地址

2020/05/16 更新:

swag 升级到了 v1.6.5,返回数据格式有更新。

最新的请关注官网文档

本文最后,优化部分可以了解一下。

使用使用

安装swag-cli-及下载相关包安装swag cli 及下载相关包 {安装swag-cli-及下载相关包安装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

可以看一下自己安装的版本

    swag --version
    swag version v1.6.5

在main-go内添加注释main.go内添加注释 {在main-go内添加注释在maingo内添加注释}

    package main

    import (
    "github.com/gin-gonic/gin"
        ginSwagger "github.com/swaggo/gin-swagger"
    "github.com/swaggo/gin-swagger/swaggerFiles"
    )

    // @title Swagger Example API
    // @version 1.0
    // @description This is a sample server celler server.
    // @termsOfService https://razeen.me

    // @contact.name Razeen
    // @contact.url https://razeen.me
    // @contact.email me@razeen.me

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

    // @host 127.0.0.1:8080
    // @BasePath /api/v1

    func main() {

        r := gin.Default()
        store := sessions.NewCookieStore([]byte("secret"))
        r.Use(sessions.Sessions("mysession", store))

        r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

        v1 := r.Group("/api/v1")
        {
            v1.GET("/hello", HandleHello)
            v1.POST("/login", HandleLogin)
            v1Auth := r.Use(HandleAuth)
            {
                v1Auth.POST("/upload", HandleUpload)
                v1Auth.GET("/list", HandleList)
            }
        }

        r.Run(":8080")
    }

如上所示,们需要导入

    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就可以自动生成文档,如下:

    ➜  swaggo-gin git:(master) ✗ swag init
    2019/01/12 21:29:14 Generate swagger docs....
    2019/01/12 21:29:14 Generate general API Info
    2019/01/12 21:29:14 create docs.go at  docs/docs.go

然后们导入这个自动生成的docs包,运行:

    package main

    import (
    "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
    // ...
```golang
    ➜  swaggo-gin git:(master) ✗ go build
    ➜  swaggo-gin git:(master) ✗ ./swaggo-gin
    [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    /api/v1/hello             --> main.HandleHello (3 handlers)
    [GIN-debug] POST   /api/v1/login             --> main.HandleLogin (3 handlers)
    [GIN-debug] POST   /upload                   --> main.HandleUpload (4 handlers)
    [GIN-debug] GET    /list                     --> main.HandleList (4 handlers)
    [GIN-debug] GET    /swagger/*any             --> github.com/swaggo/gin-swagger.WrapHandler.func1 (4 handlers)
    [GIN-debug] Listening and serving HTTP on :8080

浏览器打开http://127.0.0.1:8080/swagger/index.html, 们可以看到如下文档标题已经生成。

在Handle函数上添加注释在Handle函数上添加注释 {在handle函数上添加注释在handle函数上添加注释}

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

    // @Summary 测试SayHello
    // @Description 向你说Hello
    // @Tags 测试
    // @Accept mpfd
    // @Produce json
    // @Param who query string true "人名"
    // @Success 200  string "{"msg": "hello Razeen"}"
    // @Failure 400  string "{"msg": "who are you"}"
    // @Router /hello [get]
    funcHandleHello(c *gin.Context) {
        who := c.Query("who")

    if who == "" {
            c.JSON(http.StatusBadRequest, gin.H)
    return
        }

        c.JSON(http.StatusOK, gin.H)
    }

们再次swag init, 运行一下。

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

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

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

Tags

Tags 是用来给API分组的。

Accept

接收的参数类型,支持表单(mpfd) , JSON(json)等,更多如下表。

Produce

返回的数据结构,一般都是json

Param

参数,从前往后分别是:

@Param who query string true “人名”

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

1.参数名

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

2.参数类型

参数类型主要有四种:

path 该类型参数直接拼接在URL中,如DemoHandleGetFile

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

query 该类型参数一般是组合在URL中的,如DemoHandleHello

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

formData 该类型参数一般是POST,PUT方法所用,如DemoHandleLogin

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

bodyAcceptJSON格式时,们使用该字段指定接收的JSON类型

    // @Param param body main.JSONParams true "需要上传的JSON"

3.参数数据类型

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

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

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

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

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响应码3.响应数据类型4.其他描述```

1.HTTP响应码

也就是200,400,500那些。

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

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

  • 自定义类型

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

    // @Success 200  main.File

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

    // @Success 200  main.File

将如你只是返回其他的数据格式可如下写:

    // @Success 200  string ""

4.其他描述

可以添加一些说明。

Failure

​ 同Success。

Router

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

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

​ 不用加基础路径哦。

生成文档与测试生成文档与测试 {生成文档与测试生成文档与测试}

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

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

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

优化优化

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

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

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

    package main

    //...

    var swagHandler gin.HandlerFunc

    funcmain(){
    // ...

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

    //...
    }

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

    // +build doc

    package main

    import (
        _ "github.com/razeencheng/demo-go/swaggo-gin/docs"

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

    funcinit() {
        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地址在这里

本文章摘自https://razeencheng.com/post/go-swagger.html

原文创作:程序员khaos

原文链接:https://www.cnblogs.com/urmkhaos/p/15345317.html

更多推荐

更多
  • Camel云原生-六、将应用部署到 Kubernetes 容器被抽象成称为pod的实体。pod 由一个或多个容器以及运行这些容器的必要配置组成。这种结构是 Kubernetes 真正精心安排的。pod ...
    Apache CN

  • Camel云原生-一、欢迎来到 Apache Camel 什么是系统集成?,业务还是集成逻辑?,云原生应用,什么是 ApacheCamel?,第四的,包装应用,摘要,集成逻辑,集成路由,交流和信息,表达式语言,Java 进化,微服务,开发要求,微文件规范,运行代码,快速汽车,优步罐,容器映像,
    Apache CN

  • Camel云原生-四、使用 Apache Camel 访问数据库 关系数据库,处理异常,摘要,JPA 的持久性,使用 JPA 的参数化查询,处理,尝试捕捉最终,错误处理程序,一个例外条款, 我们在实现 API 或集成时所做的大部分工作是移动数据。我们提供数据,消费数据,转换数据,复制数据,等等。这样,
    Apache CN

  • Camel云原生-五、使用 Apache Kafka 发送消息 面向消息的中间件,ApacheKafka,Camel 和 Kafka,摘要,概念和架构,安装和运行,测试安装,设置应用,首次测试,扩大消费者规模,偏移复位,单元测试应用, 在前面的章节中,我们主要关注跨应用通信的同步方法的使用,更具体地
    Apache CN

  • Camel云原生-二、开发 REST 集成 Camel DSLs,REST 和 OpenAPI,第一个应用:REST 文件服务器,摘要,REST 接口和 OpenAPI,可读性和逻辑重用,Beans 和处理器,述语,数据格式,类型转换器, 在上一章中,向您介绍了 Apache C
    Apache CN

  • Camel云原生-三、使用 Keycloak 保护 Web 服务 访问控制,用 Keycloak 保护 REST APIs,摘要,OAuth 2.0,OpenID 连接,凯克洛克,公开联系人列表 API,配置键盘锁,配置资源服务器,使用 Camel 消费 API, 我们一直在谈论 web 服务,方法是
    Apache CN

  • Ansible2安全自动化-十、编写安全测试的 Ansible 模块 开始使用 hello world Ansible 模块,密码,建立开发环境,计划和要记住的内容,OWASP ZAP 模块,使用 Docker 创建 ZAP,创建易受攻击的应用,Ansible 模块模板,[计]元数据,记录模块,源代码模板
    Apache CN

  • Ansible2安全自动化-十一、可靠的安全最佳实践、参考和进一步阅读 十一、可靠的安全最佳实践、参考和进一步使用 Ansible 的保管库,如何对变量和文件使用 Ansible Vault,Ansible Vault 单一加密变量,Ansible 拱顶在 Ansible 塔中的应用,设置和使用可扫描集群,
    Apache CN

  • Ansible2安全自动化-九、用于取证收集和恶意软件分析的自动化实验室设置 为隔离环境的实验室创建可行的行动手册,收集文件和域恶意软件识别和分类,病毒总应用编程接口工具设置,病毒总应用编程接口扫描恶意软件样本,设置布谷鸟沙盒环境,设置布谷鸟主机,设置布谷鸟客人,使用 Ansible 行动手册提交样品和报告,使用
    Apache CN

  • Ansible2安全自动化-八、Docker 容器的持续安全扫描 理解连续安全概念,使用 Ansible 自动化 Docker 容器的漏洞评估,安全 Docker 工作台,克莱尔,为了 Docker 安全,使用 Ansible Tower 进行计划扫描,锚,锚定的引擎服务设置,锚定 cli 扫描仪,使
    Apache CN

  • 近期文章

    更多
    文章目录

      推荐作者

      更多