SpringfoxでSwaggerAPI仕様書を自動生成する (詳細設定編:2)
はじめに
こんにちは。しがないOLくにきちです。
今回は間を空けずに書きました！いつも書くのに時間がかかってしまうので、もうちょっと筆が早くなればなぁ・・・と思う今日この頃。
さて、さっそくですが本題に。
前回の 詳細設定編:1 では、API定義、API操作定義、レスポンス定義、パラメータ定義 までをご紹介しました。今回は、モデル定義、モデルプロパティ定義について紹介したいと思います。
本ブログの構成
- Swagger ドキュメントのカスタマイズ
- モデル定義（
@ApiModel） - モデルプロパティ定義（
@ApiModelProperty） - 配列やマップ構造のプロパティ表示設定
- モデル定義（
Swagger ドキュメントのカスタマイズ
ここでは、各 API やパラメータ、レスポンスなどに関する説明文などを細かく設定していきます。主に下記の設定を行います。（）内は定義する際に使用するアノテーションを記述しています。
- API定義（
@Api） - API操作定義（
@ApiOperation） - レスポンス定義（
@ApiResponses、@ApiResponse） - パラメータ定義（
@ApiParam）
---- ここまでは前回の詳細設定編:1 を参照してください ----
- モデル定義（
@ApiModel） - モデルプロパティ定義（
@ApiModelProperty）
モデル定義（@ApiModel）
モデルについて定義します。
リクエストモデルやリソースモデルに @ApiModel を用いて、モデルの説明を設定できます。
主要なメソッド
| メソッド | 説明 |
|---|---|
| value | モデル名を指定します。 (default: モデルクラス名) |
| description | モデルの説明を指定します。 |
設定例
以下の例では、レスポンスとして設定していた会員リソースモデルに説明を追加しています。
@ApiModel(description = "会員情報")
public class Member { ... }
Swagger-ui 表示例
@ApiModel 未設定時と比較してみると、description という項目が追加されているのがわかります。
ここでは value を指定していないので、クラス名である「Member」を 表示しています。
@ApiModel 設定時
@ApiModel 未設定時
モデルプロパティ定義（@ApiModelProperty）
モデルが持つ各プロパティについて定義します。
リクエストモデルやリソースモデル内で定義している各プロパティに @ApiModelProperty を用いて、プロパティの説明や入力例、プロパティの表示順序などを設定できます。
主要なメソッド
| メソッド | 説明 |
|---|---|
| value | プロパティ名を指定します。 |
| required | プロパティが必須かどうかを指定します。 (default: false) |
| example | プロパティの入力例を指定します。 |
| position | プロパティの表示順序を指定します。 (default: 0) |
設定例
@ApiModelProperty(value = "会員を一意に特定するための番号 (UUID)", example = "279818d8-89d0-43b2-9c62-a397b6a4ce50") // position 未指定(position = 0 と同じ) private String memberId; @ApiModelProperty(value = "会員の氏名", example = "クラス はなこ", position = 1) private String memberName; @ApiModelProperty(value = "会員の性別", example = "Female", position = 2) private String gender;
Swagger-ui 表示例
レスポンスの「Example Value」 を見ると、@ApiModelProperty 未設定時は各プロパティの値が 「"string"」 だったところ、「"279818d8-89d0-43b2-9c62-a397b6a4ce50"」 など具体的な入力例が追加されていることがわかります。そのほかには、プロパティ表示順が ID -> 氏名 -> 性別 の順に変更されていますね。
また、「Model」を見ると、各プロパティの説明が追加されています。
@ApiModelProperty 設定時
- Example Value
- Model
@ApiModelProperty 未設定時
- Example Value
- Model
配列やマップ構造のプロパティ表示設定
これまでの例では、String 型の単純なプロパティの設定を行いましたが、配列やマップ構造のプロパティを扱う場合があります。配列やマップ構造のプロパティは、以下のようにエスケープシーケンスを用いて設定しましょう。
// 配列構造
example = "[\"tag01\", \"tag02\"]"
// マップ構造
example = "{\"attr01\": \"value01\"}"
Swagger-ui 表示例
配列構造の tag とマップ構造の attributes というプロパティが追加されています。
今回のモデルは複雑ではないので問題ないのですが、構造によってはモデルを表示できなかったり、想定していない値が表示される、ということがあります。既存の設定でゴニョゴニョできる場合もありますが、対応できないものについては Swagger 表示用のモデルを作ることで対応しました。
まとめ
今回のカスタマイズで API ドキュメントがこのようになりました。
結構簡単に作れましたね。
Springfox の自動生成は、ソースコードに設定を記述することになるのでソースコードが見にくくなったり、手書きと比べて柔軟な表現ができない部分があります。しかし、コードと一緒にドキュメントの更新ができるので、ドキュメントの更新漏れが防ぎやすいというメリットがあります。実際、手書きでやっていた時、ちらほら実装とドキュメントの差異を発見しました。手書きに比べて記述量も少なく済み、手軽に API ドキュメントを作れるのはありがたいです。
Springfox で API ドキュメント自動生成はこれで終了。また何か それでは、今回はこの辺で。
