Swaggerで動作確認
LastaFluteでのSwagger
LastaFluteでは、Swaggerを 気軽にリクエストを送信するためのツール として活用しています。
JSON APIだと、(少なくとも開発時に)画面が存在せず気軽に Action を叩けなかったり、JSON Body のリクエストでブラウザから簡単に叩けなかったりすることが往々にしてあります。 そこで、Swaggerを活用して、気軽に動作確認できるようにしています。 (もちろん、UnitTestはしっかり書いていった方が良いですが、最終的には実際にリクエストを飛ばして動くことを確認した方が良いです)
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;
}
コード上でも、しっかりドキュメントになりますし、LastaDoc にも反映されるので、しっかり書いておけば様々なところで活躍しますので、積極的に付けていくと良いでしょう。
細かい仕様は以下のようになります。
- ダブルクォーテーションで囲うことで、空白を含めることができたり、値の後ろにコメントを書ける
- Executeメソッドのjavadocで、Pathパラメーターの引数(@param)にも付けることができる
- リストの場合は、[a, b, c] という[]形式で書く
- nullと書いたら、nullという文字列ではなく、指定してないのと同じ
@throwsレスポンスのススメ
呼び出し側の開発者に対して、どんなときに400か？どんなときに404か？ のエラーレスポンスの情報を、Swaggerを経由して伝えることができたらリモート呼び出しがよりスムーズになるでしょう。
JavaDoc の @throws を使って、Swagger UI上で400/404などの説明を表示できます。
(@since lasta-meta-0.6.1)
↓↓↓ (こうなる)
↑SwaggerUI上の Responses の欄におけるHTTPステータスコードごとの説明の箇所です。
元々デフォルトで表示されているLastaFlute自体が戻すクライアントエラー系のレスポンス情報に加えて、該当のActionクラスの "Executeメソッド" のJavaDoc上の @throwsで書いた情報を載せることができます。"::" の後がそれら情報になります。
各Actionクラスの開発者が、呼び出し側の開発者にSwaggerを経由して具体的なエラーレスポンスの情報を伝えることができるようになります。
@throwsレスポンスの書き方
ActionのExecuteメソッドのJavaDocにおいて、(JavaDoc標準の)@throwsを記載します。 その行の最後に "その例外が紐付くHTTPステータス" を (...) 形式で表現します。
e.g. throws response format @Java
/**
* @throws 例外クラス名 どんな時に発生するかの説明 (HTTPステータスコード)
*/
e.g. use throws response in javadoc in Maven @Java
/**
* This is the first line of execute method java-doc. <br>
* And the second line is here.
* @param body Oh yeah nice body (NotNull)
* @return same as body (tekito) (NotNull)
* @throws EntityAlreadyDeletedException When the resource is not found. (404)
* @throws EntityAlreadyUpdatedException When the resource already has been updated. (400)
* @throws EntityAlreadyExistsException When the resource already exists. (400)
*/
@Execute
public JsonResponse<WxLastametaHascladocBody> index(WxLastametaHascladocBody body) {
...
このように書いておくと、SwaggerUI上にも @throws の説明が表示されるようになります。
例外とHTTPステータスの関係性
どの例外でどのHTTPステータスになるか？は、アプリ上の[App]ApiFailureHookの実装などによって変わりますので、そこはActionクラスの開発者が把握して正確に書きましょう。
ちなみに、LastaFluteのExampleデフォルトでは、基本的に業務例外は400で戻すようになっています。 現場での実装も同じであれば、"こういう状況は400, ああいう状況も400" というように、ひたすら400に対して "どんな時に400になるか？" の説明を追加していくことが想像されます。
ただ、キリがないものではあるので、全部の可能性を列挙するというよりも... "呼び出し側に伝えておいた方が良いだろう" というものに限定して記載するのが現実的ではあると想定しています。
