api响应泛型参数 swagger_【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 通常会展示如下信息：

1. HTTP 方法(GET、POST、PUT、DELETE 等)

2. URL 路径

3. HTTP