[解決済み] swagger で @ApiParam または @ApiModelProperty を使用しますか？

質問

swagger-ui docsにメタデータを追加するには、次の両方のアノテーションが機能します。どちらを優先すべきですか？その理由は？

public class MyReq {

    @ApiModelProperty(required = true, value = "the persons name")
    @ApiParam(required = true, value = "the persons name")
    private String name;
}

@RestController
public class MyServlet {
   @RequestMapping("/") 
   public void test(MyReq req) {

   }
}

解決方法は？

この2つには大きな違いがあります。どちらもswaggerにメタデータを追加するために使用されますが、追加されるメタデータが異なります。

@ApiParam はパラメータ用です。通常、API Resourceのリクエストクラスで定義されます。

ApiParamの例です。

/users?age=50

は、パラメータエイジと以下のフィールドを定義するために使用することができます。

• paramType: クエリ
• 名前：年齢
• 説明: ユーザーの年齢
• 必須: true

@ApiModelProperty は、モデルのプロパティを追加するために使用します。 モデルクラス内のモデルプロパティで使用することになります。

例

モデルUserはnameとageをプロパティとして持っており、それぞれのプロパティに対して以下のように定義できます。

年齢の場合

• タイプ: 整数。
• format": int64。
• 説明: ユーザーの年齢。

swaggerオブジェクトでそれぞれが示すフィールドを確認します。

ApiModelProperty- https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#529-property-object

ApiParam - https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#524-parameter-object