【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
-
在 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 服务器的最终源码。
正文到此结束
热门推荐
相关文章
Loading...
![[HBLOG]公众号](http://www.liuhaihua.cn/img/qrcode_gzh.jpg)
