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 ドキュメント自動生成はこれで終了。また何か それでは、今回はこの辺で。