メインコンテンツにスキップ

Swaggerファイルの生成

概要​

ご存知の通り、beegoフレームワークは「bee」というコマンドラインツールを使ってSwaggerファイルを生成し、APIを明確にするサポートを提供しています。 Casdoorもbeegoをベースに構築されています。 しかし、beeによって生成されたSwaggerファイルは、「@Tag」ラベルを使ってAPIを分類することに失敗していることがわかりました。 そこで、この機能を実装するために元の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() {

同じ「@Tag」ラベルを持つAPIは同じグループに入れられます。

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. (オプション) 特定のタグや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"

    特筆すべき点：複数のタグやAPIを提供する際には、カンマ,のみをセパレータとして受け付けます。

そうすると、新しいSwaggerファイルが生成されたことがわかります。