SpringfoxでSwaggerAPI仕様書を自動生成する (詳細設定編:1)
はじめに
こんにちは。しがないOLくにきちです。
ブログ書くのが少し空いてしまっていたら、いつの間にか Springfox のバージョンが上がって 2.7.0 -> 2.8.0 になっておりました！ヽ(▽｀)ノﾜｰｲ♪
前回のブログで設定した内容に追加をしたいと思いますので、後述します。
本ブログの構成
- バージョンアップに伴う設定の追加
- Swagger ドキュメントのカスタマイズ
- API定義（
@Api） - API操作定義（
@ApiOperation） - レスポンス定義（
@ApiResponses、@ApiResponse） - パラメータ定義（
@ApiParam）
- API定義（
バージョンアップに伴う設定の追加
冒頭で書きましたが、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）について書きたいと思います。
