跳到主内容

生成 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文件已经生成。