Перейти к основному содержанию

Генерация файлов Swagger

Обзор​

Как мы знаем, фреймворк beego поддерживает генерацию файлов swagger для уточнения API с помощью командной строки, называемой "bee". Casdoor также построен на основе beego. Однако мы обнаружили, что файлы swagger, сгенерированные с помощью bee, не могли категоризовать API с пометкой "@Tag". Поэтому мы изменили оригинальный bee, чтобы реализовать эту функцию.

Как написать комментарий​

Большинство правил полностью идентичны форматам комментариев оригинального bee. Единственное несоответствие заключается в том, что 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() {

API с одинаковыми метками "@Tag" будут помещены в одну группу.

Как сгенерировать файл swagger​

  1. Напишите комментарии к API в правильном формате.

  2. Склонируйте этот репозиторий: https://github.com/casbin/bee.

  3. Соберите модифицированный bee. Например, в корневом каталоге casbin/bee, выполните следующую команду:

    go build -o mybee .

  4. Скопируйте mybee в базовый каталог casdoor.

  5. В этом каталоге выполните следующую команду:

    mybee generate docs

  6. (Необязательно) Если вы хотите сгенерировать документ swagger для конкретных тегов или API, вот некоторые примеры команд:

    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"

    Важно: Мы принимаем только запятую , в качестве разделителя, когда предоставлено несколько тегов/API.

Затем вы обнаружите, что сгенерированы новые файлы swagger.