swaggo 生成接口文档

date

icon

slug

status

前言

现在一般的项目都采用流行的前后端分离进行开发，但是存在的问题就是前后端的沟通问题，为了减少沟通成本，便有了接口文档这种东西。但是却又存在代码和文档分离的情况，经常性发生实际接口和文档描述情况不一致等情况，反而徒增了沟通成本（互相甩锅）。

于是最终选择了swaggo进行接口文档的生成，它能够根据代码中的注释来实时更新代码文档，确保了交付给别人的代码和文档是一一对应的。

Swagger 是一个开源的 API 设计和文档工具，它可以帮助开发人员更快、更简单地设计、构建、文档化和测试 RESTful API。Swagger 可以自动生成交互式 API 文档、客户端 SDK、服务器 stub 代码等，从而使开发人员更加容易地开发、测试和部署 API。

在go1.16后使用go install 代替go get

查看是否安装成功

如仍旧提示Command not found，先前往$GOPTAH/bin下查看是否有swag的可执行文件，如果有的话可以将$GOPATH/bin目录添加至环境变量。

1.首先为每个接口根据swagger要求写好对应的声明式注释

2.使用swag工具进行文档生成

3.使用web框架对应的handler进行接口渲染和部署

格式化swagger注解

生成文档

使用-g指定入口文件，为了拿到所有接口，要在项目根目录执行该命令，执行完会在根目录下新建一个docs文件夹，里面存放的就是相应的接口文档，此时已经可以本地进行浏览了。

根据不同web框架引入对应的handler，gin-swgger，fiber/swagger等

运行项目即可在浏览器看到接口文档。