Passer au contenu principal

Génération de fichiers Swagger

Vue d'ensemble​

Comme nous le savons, le framework beego fournit un support pour la génération de fichiers swagger afin de clarifier l'API via l'outil de ligne de commande appelé "bee". Casdoor est également construit sur la base de beego. Cependant, nous avons constaté que les fichiers swagger générés par bee ne parvenaient pas à catégoriser les API avec l'étiquette "@Tag". Ainsi, nous avons modifié le bee original pour implémenter cette fonction.

Comment écrire le commentaire​

La plupart des règles sont exactement identiques aux formats de commentaire du bee original. La seule divergence est que l'API doit être divisée en différents groupes selon l'étiquette "@Tag". Par conséquent, les développeurs sont obligés de s'assurer que cette étiquette est correctement ajoutée. Voici un exemple :

// @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() {

Les API avec les mêmes étiquettes "@Tag" seront mises dans le même groupe.

Comment générer le fichier swagger​

  1. Écrivez des commentaires pour l'API dans le format correct.

  2. Récupérez ce dépôt : https://github.com/casbin/bee.

  3. Construisez le bee modifié. Par exemple, dans le répertoire racine de casbin/bee, exécutez la commande suivante :

    go build -o mybee .

  4. Copiez mybee dans le répertoire de base de casdoor.

  5. Dans ce répertoire, exécutez la commande suivante :

    mybee generate docs

  6. (Facultatif) Si vous souhaitez générer un document swagger pour des tags ou des apis spécifiques, voici quelques commandes d'exemple :

    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"

    Notamment : Nous n'acceptons qu'une virgule , comme séparateur lorsque plusieurs tags/apis sont fournis.

Ensuite, vous constaterez que les nouveaux fichiers swagger sont générés.