跳到主内容

生成 Swagger 文件

概述​

我们知道，beego框架提供了生成swagger文件的支持，以通过名为"bee"的命令行工具来阐明API。 Casdoor也是基于beego构建的。 然而，我们发现由bee生成的swagger文件未能使用“@Tag”标签对API进行分类。 所以，我们修改了原始的蜜蜂以实现这个功能。

如何写comment​

大多数规则与原始蜜蜂注释格式完全相同。 唯一的差异在于，API应根据“@Tag”标签划分为不同的组。 因此，开发者有责任确保这个标签被正确添加。 这是一个例子：

// @Title Login
// @Tag Login API
// @Description login
// @Param   oAuthParams     query    string  true        "oAuth parameters"
// @Param   body    body   RequestForm  true        "Login information"
// @Success 200 {object} controllers.api_controller.Response The Response object
// @router /login [post]
func (c *ApiController) Login() {

带有相同“@Tag”标签的API将被放入同一组。

如何生成swagger文件​

  1. 以正确的格式为API编写注释。

  2. 获取此仓库：https://github.com/casbin/bee。

  3. 构建修改后的蜜蜂。 例如，在casbin/bee的根目录中，运行以下命令：

    go build -o mybee .

  4. 将mybee复制到casdoor的基础目录。

  5. 在那个目录中，运行以下命令：

    mybee generate docs

  6. (可选) 如果你想为特定的标签或API生成swagger文档，以下是一些示例命令：

    mybee generate docs --tags "Adapter API"
    mybee generate docs --tags "Adapter API,Login API"
    mybee generate docs --apis "add-adapter"
    mybee generate docs --apis "add-adapter,delete-adapter"

    值得注意的是：当提供多个标签/接口时，我们只接受逗号,作为分隔符。

然后你会发现新的swagger文件已经生成。