Перейти до основного вмісту

Генерація файлів 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.