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 では、 patternsize などを定義するBeanValidatorPluginsConfiguration というプラグインを設定しても Swagger-ui で正しく表示されていませんでした。このバージョンアップデートを機に、BeanValidatorPluginsConfiguration が機能するようになっていましたので、設定を追加します。
設定は簡単で、前回作成した Swaggerドキュメント定義クラス SwaggerConfigurationBeanValidatorPluginsConfiguration.class を import するだけです。この設定により、ソースコードから patternsize を自動的に抽出、表示できるようになります。

ライブラリの追加

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 を用います。
GETDELETE などの 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 表示例

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

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

まとめ

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