Swagger@ApiParamと@ApiModelProperty

投稿日: 2022-10-31 2022-10-31
タグ: Java, REST, Swagger

1. 概要

このチュートリアルでは、Swaggerの@ApiParamおよび@ApiModelPropertyアノテーションについて簡単に説明します。さらに、これらの注釈を比較し、それぞれの正しい使用法を特定します。

2. 主な違い

簡単に言えば、@ApiParamアノテーションと@ApiModelPropertyアノテーションはSwaggerに異なるメタデータを追加します。 @ApiParam アノテーションは、APIリソースリクエストのパラメーター用ですが、 @ApiModelProperty モデルのプロパティ用です。

3. @ApiParam

@ApiParam アノテーションは、 @PathParam 、@QueryParam[などのJAX-RS1.x/2.xパラメーターアノテーションでのみ使用されます。 X148X]、 @HeaderParam 、 @FormParam 、および@BeanParam。 swagger-core はデフォルトでこれらのアノテーションをスキャンしますが、 @ApiParam を使用して、パラメーターの詳細を追加したり、コードから読み取られる値を変更したりできます。

@ApiParamアノテーションは、パラメーターの名前、タイプ、説明（値）、および値の例を指定するのに役立ちます。さらに、パラメーターが必須かオプションかを指定できます。

その使用法を見てみましょう：

@RequestMapping(
    method = RequestMethod.POST,
    value = "/createUser",
    produces = "application/json; charset=UTF-8")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@ApiOperation(value = "Create user",
  notes = "This method creates a new user")
public User createUser(
  @ApiParam(
    name =  "firstName",
    type = "String",
    value = "First Name of the user",
    example = "Vatsal",
    required = true)
  @RequestParam String firstName) {
 
    User user = new User(firstName);
    return user;
}

@ApiParamの例のSwaggerUI表現を見てみましょう。

それでは、@ApiModelPropertyを見てみましょう。

4. @ApiModelProperty

@ApiModelProperty アノテーションを使用すると、説明（値）、名前、データ型、値の例、モデルプロパティの許可値など、Swagger固有の定義を制御できます。

また、特定のシナリオでプロパティを非表示にする場合に備えて、追加のフィルタリングプロパティを提供します。

ユーザーのfirstNameフィールドにいくつかのモデルプロパティを追加しましょう。

@ApiModelProperty(
  value = "first name of the user",
  name = "firstName",
  dataType = "String",
  example = "Vatsal")
String firstName;

それでは、SwaggerUIでのUserモデルの仕様を見てみましょう。

5. 結論

この簡単な記事では、パラメーターとモデルプロパティのメタデータを追加するために使用できる2つのSwaggerアノテーションについて説明しました。次に、これらのアノテーションを使用していくつかのサンプルコードを確認し、SwaggerUIでの表現を確認しました。

いつものように、これらのコードサンプルはすべてGitHubで利用できます。

getdocs

13036