SpringfoxでSwaggerAPI仕様書を自動生成する (詳細設定編:1)

はじめに

こんにちは。しがないOLくにきちです。
ブログ書くのが少し空いてしまっていたら、いつの間にか Springfox のバージョンが上がって 2.7.0 -> 2.8.0 になっておりました！ヽ(▽｀)ノﾜｰｲ♪
前回のブログで設定した内容に追加をしたいと思いますので、後述します。

本ブログの構成

• バージョンアップに伴う設定の追加
• Swagger ドキュメントのカスタマイズ
  • API定義（@Api）
  • API操作定義（@ApiOperation）
  • レスポンス定義（@ApiResponses、@ApiResponse）
  • パラメータ定義（@ApiParam）

バージョンアップに伴う設定の追加

冒頭で書きましたが、Springfox のバージョンが 2.7.0 -> 2.8.0 になりました。
このアップデートで Swagger-ui が 3系 になっているので、見た目がガラリと変わります。
また、前回のバージョン 2.7.0 では、 pattern や size などを定義するBeanValidatorPluginsConfiguration というプラグインを設定しても Swagger-ui で正しく表示されていませんでした。このバージョンアップデートを機に、BeanValidatorPluginsConfiguration が機能するようになっていましたので、設定を追加します。
設定は簡単で、前回作成した Swaggerドキュメント定義クラス SwaggerConfiguration に BeanValidatorPluginsConfiguration.class を import するだけです。この設定により、ソースコードから pattern や size を自動的に抽出、表示できるようになります。

ライブラリの追加

compile "io.springfox:springfox-bean-validators:$springfoxVersion"

SwaggerConfigurationの設定追加

@EnableSwagger2
@Configuration
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
    .....
}

Swagger ドキュメントのカスタマイズ

ここでは、各 API やパラメータ、レスポンスなどに関する説明文などを細かく設定していきます。
主に下記の設定を行います。（）内は定義する際に使用するアノテーションを記述しています。
※ 前編・後編にわけます。

• API定義（@Api）
• API操作定義（@ApiOperation）
• レスポンス定義（@ApiResponses、@ApiResponse）
• パラメータ定義（@ApiParam）
• モデル定義（@ApiModel）
• フィールド定義（@ApiModelProperty）

では、それぞれの設定について説明します。

API定義（@Api）

API リソースについて定義します。
Controller クラスに @Api を付加し、API のタグや説明などを設定することができます。

主要なメソッド

メソッド	説明
tags	API の tag を指定します。（複数可） 指定したタグごとにカテゴライズされて表示されます。
description	API の簡単な説明を指定します。（default: クラス名）

設定例

以下の例では、会員情報の操作を行う API として、「Member」というタグを設定しています。

@Api(
    tags = "Member",
    description = "Member operations"
)
public class MemberController { ... }

Swagger-ui 表示例

API操作定義（@ApiOperation）

API リソース内の単一の操作について定義します。
Controller 内で定義している HTTP メソッドに @ApiOperation を付加し、操作に関する説明を設定することができます。

主要なメソッド

メソッド	説明
value	API の簡単な説明を指定します。（summaryフィールドに相当）
description	API の詳細な説明を指定します。（notesフィールドに相当）

設定例

以下の例では、会員登録操作に関する説明を設定しています。

@ApiOperation(
    value = "会員情報を登録します",
    notes = "会員情報を登録します。結果として作成した会員情報を返します。"
)
@RequestMapping(method = RequestMethod.POST)
public ResponseEntity<Resource<Member>> createMember( ... ) { ... }

Swagger-ui 表示例

POST や /members を設定せずにソースコードから情報を抽出して表示していることがわかります。
※ ただし、/members API群 を表示するには SwaggerConfiguration にて対象とする RequestHandler(/members/**) を定義する必要があります。詳しくは前回の環境設定編をご確認ください。

レスポンス定義（@ApiResponses、@ApiResponse）

レスポンスについて定義します。 Controller 内で定義している HTTP メソッドに @ApiResponses や @ApiResponse を用いて、HTTPステイタスコードやレスポンスに関する説明を設定することができます。レスポンスが複数存在する際に @ApiResponses を用います。
※ GET、DELETE などの HTTP メソッド毎にレスポンスを設定することができます。同じ記述を何度も行うのは手間なので、SwaggerConfiguration で共通レスポンスを定義することも検討しましょう。詳しくは前回の環境設定編をご確認ください。

主要なメソッド(@ApiResponse)

メソッド	説明
code	HttpStatusCode を指定します。（ ResponseのCodeフィールドに相当）
message	レスポンスの説明を指定します。（ ResponseのDescriptionフィールドに相当）
response	レスポンスとなるモデルを指定します。（ Response のExample Value / Model に相当）

設定例

以下の例では、成功時に Member 、失敗時には ErrorResponse を表示するように設定しています。

// ApiOperation は省略
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "登録した会員情報", response = Member.class),
    @ApiResponse(code = 400, message = "リクエストに必須の項目が不足、または不正な値を指定している。", response = ErrorResponse.class),
    @ApiResponse(code = 409, message = "指定した識別子が、既存の識別子と重複している。", response = ErrorResponse.class)
})
@RequestMapping(method = RequestMethod.POST)
public ResponseEntity<Resource<Member>> createMember( ... ) { ... }

Swagger-ui 表示例

Model を見ると pattern を設定せずにソースコードから情報を抽出して表示していることがわかります。
これは、最初に設定した BeanValidatorPluginsConfiguration によるものです。
また、レスポンスの各フィールドに説明などを設定したい場合は、response で指定したモデルクラス（例えば Member.class）に @ApiModelProperty を用いて定義する必要があります。（現時点では設定していない状態です。）

パラメータ定義（@ApiParam）

パラメータについて定義します。 HTTP メソッドの引数に @ApiParam を付加し、リクエストパラメータに関する説明を設定することができます。

主要なメソッド

メソッド	説明
name	パラメータ名を指定します。（default: 引数名）
required	パラメータの説明を指定します。（default: 引数名）
value	パラメータが必須かどうかを指定します。（default: false）

設定例

以下の例では、会員情報登録のリクエストに関する設定をしています。
あえて request という名前を body に変換していますが、そのままの名前で問題ない場合は、 name の設定は不要です。

public ResponseEntity<Resource<Member>> createMember(
    @ApiParam(name = "body", required = true, value = "登録する会員情報")
    @Validated @RequestBody CreateMemberRequest request) { ... }

Swagger-ui 表示例

パラメータのタイプ（body や path 等）を設定せずに、ソースコードから情報を抽出して表示していることがわかります。レスポンス同様、こちらの Model も pattern を設定せずにソースコードから情報を抽出して表示しています。

ここまでの設定における Swagger-ui 表示例

まとめ

ちょっと長くなって来たので、今回は一旦ここまで。
今回は詳細設定編として、API定義、API操作定義、レスポンス定義、パラメータ定義 までを簡単に書いてみました。Springfox は、Spring の機能を利用して Swagger ドキュメントを生成するので、細かく設定を記述する必要がないところが良いですね。
次回は、モデル定義（@ApiModel）、フィールド定義（@ApiModelProperty）について書きたいと思います。