web-dev-qa-db-ja.com

swaggerで@ApiParamまたは@ApiModelPropertyを使用しますか？

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

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) {

   }
}
javaswaggerswagger-uiswagger-2.0
10
membersound

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

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

@ApiParamの例：

/users?age=50

パラメータの経過時間と次のフィールドを定義するために使用できます。

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

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

例：

モデルユーザーは、プロパティとして名前と年齢を持ちます。名前と年齢は、プロパティごとに次を定義できます。

年齢について：

  • タイプ：整数、
  • 形式」：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

14
slal