跳到主内容

生成Swagger文档

Casdoor基于beego构建，该框架使用beeCLI生成Swagger文件。 默认的bee不会按标签对API进行分组；Casdoor使用的是一个经过修改的bee，该bee支持@Tag标签，因此生成的文档中会按标签对API进行分组。

备注

The built-in Swagger UI at /swagger is only served when Casdoor runs in dev run mode (runmode = dev in conf/app.conf). It is not exposed in production.

评论格式​

使用与标准蜂鸟相同的注释样式；唯一的额外要求是**@标签**以便对 API 进行分组。 示例：

// @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输出中会显示在同一个分组中。

生成Swagger文件​

  1. 请在您的API处理程序中添加上述格式的注释（包括@Tag)。

  2. 克隆修改后的bee：https://github.com/casbin/bee。

  3. 在仓库根目录中构建bee：

    go build -o mybee .

  4. 将mybee复制到Casdoor项目根目录。

  5. 从Casdoor根目录运行：

    mybee generate docs

  6. （可选）为特定标签或API生成文档：

    mybee 生成文档 --tags “适配器 API”   mybee 生成文档 --tags “适配器 API，登录 API”   mybee 生成文档 --apis “添加适配器”   mybee 生成文档 --apis “添加适配器，删除适配器”

    仅在列出多个标签或API时使用逗号,。

生成的Swagger文件将显示在Casdoor项目中。