Swaggerで動作確認

LastaFluteでのSwagger

LastaFluteでは、Swaggerを 気軽にリクエストを送信するためのツール として活用しています。

JSON APIだと、(少なくとも開発時に)画面が存在せず気軽に Action を叩けなかったり、JSON Body のリクエストでブラウザから簡単に叩けなかったりすることが往々にしてあります。 そこで、Swaggerを活用して、気軽に動作確認できるようにしています。 (もちろん、UnitTestはしっかり書いていった方が良いですが、最終的には実際にリクエストを飛ばして動くことを確認した方が良いです)

SwaggerUIの概要

Swaggerの環境セットアップ

そもそも、Swaggerの環境が整っていなければ、セットアップしましょう。

Swaggerの使い方

アプリを起動して、/swagger にアクセスします。

TODO jflute 画面の画像を入れたりして、簡単な使い方の説明を書きたい

e.g.デフォルト値のススメ

どんな値をリクエストすればいいのかわからない問題

Swaggerで、どんな形のJSONを投げればいいのか? がわかっても、それぞれの項目に具体的にどんな業務的な値を入れたらいいのか? がわからないと、結局スムーズにリクエストを飛ばすことができません。Swaggerを起動するたびにつどつど入力するのも大変です。

JavaDocにe.g.でデフォルト値を記載

Form や JSON Body などのフィールドの JavaDoc に、e.g. で "例えば、こんな値" という値を記載しておけば、それが Swagger 上のデフォルト値として扱われます。

これを、e.g.デフォルト値 (いーじーでふぉるとち) と呼びます。

e.g. use "e.g." in javadoc in Maven @Java
public class ProductSearchBody {

    /** keyword of product name e.g. Stranger */
    @Length(max = 10)
    public String productName;

    /** status of product e.g. ONS */
    public CDef.ProductStatus productStatus;

    /** keyword of member name that purchases e.g. S */
    @Length(max = 5)
    public String purchaseMemberName;
}

SwaggerUIでe.g.デフォルト値

コード上でも、しっかりドキュメントになりますし、LastaDoc にも反映されるので、しっかり書いておけば様々なところで活躍しますので、積極的に付けていくと良いでしょう。

細かい仕様は以下のようになります。

  • ダブルクォーテーションで囲うことで、空白を含めることができたり、値の後ろにコメントを書ける
  • Executeメソッドのjavadocで、Pathパラメーターの引数(@param)にも付けることができる
  • リストの場合は、[a, b, c] という[]形式で書く
  • nullと書いたら、nullという文字列ではなく、指定してないのと同じ