java 的 Swagger - 必填字段阻止执行
Swagger for java - the required field prevents execution
我正在使用具有以下 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 调用此函数时,它运行良好。但是,我不能再用招摇的 UI 来测试了。我不知道这是为什么?我什至尝试为其中之一设置 schema
字段(我认为 swagger 可能需要知道如何验证)但这没有帮助。所以现在,当我填写这些字段时,swagger 以红色突出显示它们并拒绝执行此 API 调用。 当我将鼠标悬停在红色框上时,它显示“未提供必填字段”。
我在网上查了一下,但找不到一组很好的示例来说明如何在 swagger 中为 java 正确设置所需参数,我也找不到描述 API 的细微差别的 API =28=]版本。
所以我的问题是 - 如何正确设置所需的参数,使它们仍然可以通过 swagger 执行 UI?
我找到问题了。
如果你注意到上面的代码,我在 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 调用。
我正在使用具有以下 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 调用此函数时,它运行良好。但是,我不能再用招摇的 UI 来测试了。我不知道这是为什么?我什至尝试为其中之一设置 schema
字段(我认为 swagger 可能需要知道如何验证)但这没有帮助。所以现在,当我填写这些字段时,swagger 以红色突出显示它们并拒绝执行此 API 调用。
我在网上查了一下,但找不到一组很好的示例来说明如何在 swagger 中为 java 正确设置所需参数,我也找不到描述 API 的细微差别的 API =28=]版本。
所以我的问题是 - 如何正确设置所需的参数,使它们仍然可以通过 swagger 执行 UI?
我找到问题了。
如果你注意到上面的代码,我在 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 调用。