annotations - 定义openapi/swagger注解的常用参数

Question

在https://swagger.io/docs/specification/describing-parameters/ (OAS3) 上有一个通用参数的示例，可以通过 $ref 在路径和操作中引用：

components:
  parameters:
    offsetParam:  # <-- Arbitrary name for the definition that will be used to refer to it.
                  # Not necessarily the same as the parameter name.
      in: query
      name: offset
      required: false
      schema:
        type: integer
        minimum: 0
      description: The number of items to skip before starting to collect the result set.
    limitParam:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 20
      description: The numbers of items to return.
paths:
  /users:
    get:
      summary: Gets a list of users.
      parameters:
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: OK
  /teams:
    get:
      summary: Gets a list of teams.
      parameters:
        - $ref: '#/components/parameters/offsetParam'
        - $ref: '#/components/parameters/limitParam'
      responses:
        '200':
          description: OK

我将如何声明 Swagger Annotations 以产生此输出，尤其是在参数是原始类型的情况下？

我试过了

@Schema(type = "int")
@OpenAPIDefinition(info = @Info(description = "descr"))
public class OffsetParam {
    public static final String DESCRIPTION =
            "The number of items to skip before starting to collect the result set.";

    @Parameter(description = "desc1")
    public static OffsetParam valueOf(String value) {
        return null;
    }
}

但我只得到

 "components" : {
    "schemas" : {
      "OffsetParam" : {
        "type" : "object"
      },...

您知道要向 JAX-RS 2.1 资源添加哪些 v3 注释吗？我的目标是一次性定义这些常用参数，并在我的应用程序的所有资源中引用它们。

标签： annotationsjax-rsswaggeropenapi