转载

【Go API 开发实战 23】进阶 9：生成 Swagger 在线文档

生成 Swagger 在线文档

本节核心内容

如何给 API 添加 Swagger 文档功能
如何编写 API 文档

本小节源码下载路径：demo17

可先下载源码到本地，结合源码理解后续内容，边学边练。

本小节的代码是基于 demo16 来开发的。

背景

开发 API 服务，API 文档必不可少，很多人选择手写 API 文档，手写 API 文档有很多问题，比如工作量大、手写容易出错、更新麻烦、格式不固定、维护困难等。所以在实际的开发中，建议自动生成 API 文档。

本教程所用的 API 服务器 RESTful 框架采用的是 gin ， gin 在 GitHub 上有很多 middleware 可用，其中就有可以自动生成 Swagger 文档的 gin-swagger middleware。

Swagger 简介

Swagger 是一个强大的 API 文档构建工具，可以自动为 RESTful API 生成 Swagger 格式的文档，可以在浏览器中查看 API 文档，也可以通过调用接口来返回 API 文档（JSON 格式）。Swagger 通常会展示如下信息：

HTTP 方法（GET、POST、PUT、DELETE 等）
URL 路径
HTTP 消息体（消息体中的参数名和类型）
参数位置
参数是否必选
返回的参数（参数名和类型）
请求和返回的媒体类型

Swagger 还有一个强大的功能：可以通过 API 文档描述的参数来构建请求，测试 API。

浏览器访问截图：

JSON 返回截图：

Swagger 配置步骤

我们用 gin-swagger gin middleware来生成 Swagger API 文档。步骤如下：

swag

$ mkdir -p $GOPATH/src/github.com/swaggo
$ cd $GOPATH/src/github.com/swaggo
$ git clone https://github.com/swaggo/swag
$ cd swag/cmd/swag/
$ go install -v

因为该包引用 golang.org 中的包，而网络环境原因，一般很难连上 golang.org ，所以这里不采用 go get 方式安装。

swag 的依赖包已经包含在第 4 节的 vendor 包下。

swag init

$ cd $GOPATH/src/apiserver
$ swag init

gin-swagger

$ cd $GOPATH/src/github.com/swaggo
$ git clone https://github.com/swaggo/gin-swagger

在 router/router.go 中添加 swagger 路由（详见 demo17/router/router.go）
编写 API 注释，Swagger 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件

这里用创建用户 API 来举例，其它 API 请参考 demo17/handler/user 下的 API 文件。

package userimport (
    ...
)// @Summary Add new user to the database// @Description Add a new user// @Tags user// @Accept  json// @Produce  json// @Param user body user.CreateRequest true "Create a new user"// @Success 200 {object} user.CreateResponse "{"code":0,"message":"OK","data":{"username":"kong"}}"// @Router /user [post]func Create(c *gin.Context) {
    ...
}

执行 swag init ，在 apiserver 根目录下生成 docs 目录

$ swag init

文档语法说明

Summary：简单阐述 API 的功能
Description：API 详细描述
Tags：API 所属分类
Accept：API 接收参数的格式
Produce：输出的数据格式，这里是 JSON 格式
Param：参数，分为 6 个字段，其中第 6 个字段是可选的，各字段含义为：

参数名称
参数在 HTTP 请求中的位置（body、path、query）
参数类型（string、int、bool 等）
是否必须（true、false）
参数描述
选项，这里用的是 default() 用来指定默认值

Success：成功返回数据格式，分为 4 个字段

HTTP 返回 Code
返回数据类型
返回数据模型
说明

路由格式，分为 2 个字段：

API 路径
HTTP 方法

API 文档编写规则请参考 See Declarative Comments Format。

API 文档有更新时，要重新执行 swag init 并重新编译 apiserver。

编译并运行

下载 apiserver_demos 源码包（如前面已经下载过，请忽略此步骤）

$ git clone https://github.com/lexkong/apiserver_demos

将 apiserver_demos/demo17 复制为 $GOPATH/src/apiserver

$ cp -a apiserver_demos/demo17/ $GOPATH/src/apiserver

$ cd $GOPATH/src/apiserver
$ make

执行 ./apiserver 启动 apiserver 后，在浏览器中打开： http://localhost:8080/swagger/index.html 访问 Swagger 2.0 API文档。

API 总览：

点击 /login ，查看 login API 详情：

小结

本小节介绍了如何生成 Swagger 文档，并演示了具体的效果。本小节也是动手操作的最后一个小节，至此恭喜你成功构建了一个企业级的 API 服务器，demo17 即为此 API 服务器的最终源码。

原文 http://mp.weixin.qq.com/s?__biz=MzUxNjgwMDg5Mw==&mid=2247483807&idx=3&sn=e29e36be92c00708888b683047433dc1

正文到此结束

所属分类：编程技术软件架构

本文标签： tab 安装注释 src IO 源码 description 代码企业自动生成测试 GitHub ORM 编译 js API 开发 message 服务器 https RESTful 参数下载目录 git 数据 REST 数据模型 tag ip UI json http 模型 cmd 配置 HTML DDL id
版权声明： 本文为互联网转载文章，出处已在文章中说明(部分除外)。如果侵权，请联系本站长删除，谢谢。
本文海报： 生成海报一生成海报二

其他链接

关于本站

本站定位：个人技术类博客

本站作用：写博客、记日志、闲聊扯淡鼓捣技术。

问题交流

【Go API 开发实战 23】进阶 9：生成 Swagger 在线文档

生成 Swagger 在线文档

本节核心内容

背景

Swagger 简介

Swagger 配置步骤

文档语法说明

编译并运行

小结

热门推荐

相关文章

说给你听

本文目录

随机标签

书籍教程

近期评论

网站信息

其他链接

关于本站

问题交流