Swagger for java - 必填字段阻止执行

Question

我正在使用具有以下 Maven 依赖项的 swagger：

 <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.0.9</version>
    </dependency>

我写了一个API调用如下：

@Operation(
        method = "GET",
        summary = "Get alerts by Date Range",
        extensions = @Extension(name = "x-rest-api", properties = @ExtensionProperty(name = "public", value = "true")),
        parameters = {
                @Parameter(name = "startDate",
                        in = ParameterIn.QUERY,
                        description = "Get alerts from this date. `startDate` should be in GMT and 24 hour Clock",
                        example = "2020-07-15T15:57:00Z",
                        schema = @Schema(implementation = ZonedDateTime.class),
                        required = true),
                @Parameter(name = "endDate",
                        in = ParameterIn.QUERY,
                        description = "Get alerts to this date. `endDate` should be in GMT and 24 hour Clock",
                        example = "2020-07-20T15:57:00Z",
                        required = true)
        },
        responses = {
                @ApiResponse(
                        responseCode = "200",
                        description = "A list of alerts",
                        content = @Content(schema = @Schema(implementation = AlertObject .class))),
                @ApiResponse(
                        responseCode = "401",
                        description = "Invalid Bearer Token",
                        content = @Content(schema = @Schema(implementation = ApiException.class))
                )
        }
)
@GET
@Path("/old")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public AlertObject alertsByDateRange(@NotNull @Valid @QueryParam("startDate") ZonedDateTime startDate,
                                                 @NotNull @Valid @QueryParam("endDate") ZonedDateTime endDate) { ... }

以上2个参数都应该是必填参数。所以我设置了required = true。但是，一旦我将它们设置为必需，我就不再能够通过 swagger 执行此 API 调用。当我使用 Postman 调用此函数时，它运行良好。但是，我无法再使用 swagger UI 进行测试。我不知道这是为什么？我什至尝试为其中一个设置schema 字段（我认为也许招摇需要知道如何验证）但这没有帮助。所以现在，当我填写这些字段时，swagger 会以红色突出显示它们并拒绝执行此 API 调用。 当我将鼠标悬停在红色框上时，它显示“未提供必填字段”。

我在网上看了，但我找不到一套很好的例子来说明如何在 swagger for java 中正确设置所需参数，也找不到描述 java 版本细微差别的 API。

所以我的问题是 - 我如何正确设置所需的参数，以便它们仍然可以通过 swagger UI 执行？

Answer 1

我发现了问题。

如果您在上面的代码中注意到，我在 swagger 中声明了两次相同的参数。第一次是：

@Parameter(name = "startDate",
                    in = ParameterIn.QUERY,
                    description = "Get alerts from this date. `startDate` should be in GMT and 24 hour Clock",
                    example = "2020-07-15T15:57:00Z",
                    schema = @Schema(implementation = ZonedDateTime.class),
                    required = true),

第二次是：

@NotNull @Valid @QueryParam("startDate") ZonedDateTime startDate,

当我查看 yaml 时，我看到了这个：

 parameters:
  - name: startDate
    in: query
    description: Get historical alerts from this date. `startDate` should be in
      GMT and 24 hour Clock
    required: true
    schema:
      type: string
      format: date-time
    example: 2020-07-15T15:57:00Z
  ...
  - name: startDate
    in: query
    required: true
    schema:
      type: string
      format: date-time

结果该参数出现了两次。你可以分辨出哪个是哪个，因为第一个参数有描述，而第二个没有。

（我认为根本问题是两者都被认为是required，但我们只能填写1个参数。）

删除第二个声明后，我就可以使用 swagger 来测试我的 API 调用。