生成 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