一种简单的，少维护的，高效的，适用于小团队的接口文档解决方案。微调开源软件 swag，redoc 的 docker 文件。

文档生成#

通过代码来定制生成文档。#

github.com/swaggo/swag/ 生成 api 文档的方式是通过方法上面的注释，在日常开发中，我们还要去维护方法上面的注释。

如果我们请求参数有变化则要手动维护，有时候我们在使用一些框架的时候，获取参数，返回数据是一些固定的格式，尝试通过分析代码 ast 语法树来实现。

示例，gin 框架。

获取参数：我们规定 ShouldBindQuery,ShouldBindJSON 等这些方法是获取参数的方法。这些方法的第一个参数为参数，JSON Query 标识位置

// @Param data body example.ExaAttachmentCategory true “媒体库分类数据”

获取返回值：我们规定方法内最后一行的第二个参数为返回值，会生成类似

// @Success 200 {object} response.Response “添加媒体库分类” 的注释

获取 Summary：summary 为方法上的第一行注释

//@Summary GetAccountInfo 获取用户信息

获取路由：调用 c.POST c.GET 方法第一个参数

// @Router /api/v1/account/GetAccountInfo [get]

实现原理是通过代码来生成注释，然后在 swag 生成文档的时候，插入到 ast 语法树中，这就表示你也可以在方法上加上 swag 的注释，同样是可以解析的。

如果方法上是 swag 注释超过 5 行则表示这使一个 swag 注释，我们不会再根据代码来生成。

package account

import (
    "apigen/ginPkg/model/request"
    "apigen/ginPkg/service"
    "github.com/gin-gonic/gin"
)

var AccountApi = &accountApi{}

type accountApi struct{}
// GetAccountInfo 获取用户信息
// @Tags      sync
func (*accountApi) GetAccountInfo(c *gin.Context) {
    // 获取用户信息
    var req request.GetAccountInfoReq

    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(200, gin.H{"code": 0, "msg": err.Error()})
    }

    accountInfo, err := service.AccountService.GetAccountInfo(req)
    if err != nil {
        return
    }

    c.JSON(200, accountInfo)
}Copy

下面这段代码，中请求参数是类型是 request.GetAccountInfoReq，使用 shouldBindJSON 获取则表示是从请求体 body 中获取对应的注释是

// @Param     data  body  request.GetAccountInfoReq  true  "请求参数"
// @Success   200   {object}  response.AccountInfo  "成功"Copy

go install github.com/luxun9527/swag/cmd/swag@latest

swag init -dir= E:\openproject\swag\example\ginCopy

文档展示#

github.com/Redocly/redoc

redoc 的展示效果

但是只支持单个文件，通过对其 nginx 配置，Dockerfile 文件部分调整，可以实现展示一个文档列表点击哪个，展示哪个，不用再去费力维护。

具体代码

github.com/luxun9527/devops/tree/m...
再此目录下 执行 make api && make run

###

如果您觉得这个方案对您有帮助，欢迎点赞、评论或 Star 支持！您的鼓励是我持续改进和优化的动力。

具体代码和配置请参考以下仓库

github.com/luxun9527/swag/tree/mas...

github.com/luxun9527/devops/tree/m...

本作品采用《CC 协议》，转载必须注明作者和本文链接