Swagger for Java – 必填字段阻止执行

huangapple
go评论96阅读模式
英文:

Swagger for java - the required field prevents execution

问题

I am using swagger with the following Maven dependency:

  1.  <dependency>
  2.         <groupId>io.swagger.core.v3</groupId>
  3.         <artifactId>swagger-jaxrs2</artifactId>
  4.         <version>2.0.9</version>
  5.     </dependency>

I wrote an API call as follows:

  1. @Operation(
  2.         method = "GET",
  3.         summary = "Get alerts by Date Range",
  4.         extensions = @Extension(name = "x-rest-api", properties = @ExtensionProperty(name = "public", value = "true")),
  5.         parameters = {
  6.                 @Parameter(name = "startDate",
  7.                         in = ParameterIn.QUERY,
  8.                         description = "Get alerts from this date. `startDate` should be in GMT and 24-hour Clock",
  9.                         example = "2020-07-15T15:57:00Z",
  10.                         schema = @Schema(implementation = ZonedDateTime.class),
  11.                         required = true),
  12.                 @Parameter(name = "endDate",
  13.                         in = ParameterIn.QUERY,
  14.                         description = "Get alerts to this date. `endDate` should be in GMT and 24-hour Clock",
  15.                         example = "2020-07-20T15:57:00Z",
  16.                         required = true)
  17.         },
  18.         responses = {
  19.                 @ApiResponse(
  20.                         responseCode = "200",
  21.                         description = "A list of alerts",
  22.                         content = @Content(schema = @Schema(implementation = AlertObject .class))),
  23.                 @ApiResponse(
  24.                         responseCode = "401",
  25.                         description = "Invalid Bearer Token",
  26.                         content = @Content(schema = @Schema(implementation = ApiException.class))
  27.                 )
  28.         }
  29. )
  30. @GET
  31. @Path("/old")
  32. @Consumes(MediaType.APPLICATION_JSON)
  33. @Produces(MediaType.APPLICATION_JSON)
  34. public AlertObject alertsByDateRange(@NotNull @Valid @QueryParam("startDate") ZonedDateTime startDate,
  35.                                                  @NotNull @Valid @QueryParam("endDate") ZonedDateTime endDate) { ... }

The above 2 parameters are both supposed to be required parameters. So I set the required = true. However, once I set them to required, I was no longer able to execute this API call through swagger. When I used Postman to call this function it worked perfectly. However, I can no longer use the swagger UI to test. I don't know why that is? I even tried setting the schema field for one of them (I thought that perhaps swagger needed to know how to validate) but that didn't help. So now, when I fill out those fields, swagger highlights them in red and refuses to execute this API call. When I hover my mouse over the red box, it says "Required field is not provided".

I looked online but I cannot find a good set of examples of how to properly set required parameters in swagger for java, nor could I find an API that describes the nuances of the java version.

So my question is - how do I properly set up required parameters such that they are still executable through the swagger UI?

英文:

I am using swagger with the following Maven dependency:

  1.  <dependency>
  2.         <groupId>io.swagger.core.v3</groupId>
  3.         <artifactId>swagger-jaxrs2</artifactId>
  4.         <version>2.0.9</version>
  5.     </dependency>

I wrote an API call as follows:

  1. @Operation(
  2.         method = "GET",
  3.         summary = "Get alerts by Date Range",
  4.         extensions = @Extension(name = "x-rest-api", properties = @ExtensionProperty(name = "public", value = "true")),
  5.         parameters = {
  6.                 @Parameter(name = "startDate",
  7.                         in = ParameterIn.QUERY,
  8.                         description = "Get alerts from this date. `startDate` should be in GMT and 24 hour Clock",
  9.                         example = "2020-07-15T15:57:00Z",
  10.                         schema = @Schema(implementation = ZonedDateTime.class),
  11.                         required = true),
  12.                 @Parameter(name = "endDate",
  13.                         in = ParameterIn.QUERY,
  14.                         description = "Get alerts to this date. `endDate` should be in GMT and 24 hour Clock",
  15.                         example = "2020-07-20T15:57:00Z",
  16.                         required = true)
  17.         },
  18.         responses = {
  19.                 @ApiResponse(
  20.                         responseCode = "200",
  21.                         description = "A list of alerts",
  22.                         content = @Content(schema = @Schema(implementation = AlertObject .class))),
  23.                 @ApiResponse(
  24.                         responseCode = "401",
  25.                         description = "Invalid Bearer Token",
  26.                         content = @Content(schema = @Schema(implementation = ApiException.class))
  27.                 )
  28.         }
  29. )
  30. @GET
  31. @Path("/old")
  32. @Consumes(MediaType.APPLICATION_JSON)
  33. @Produces(MediaType.APPLICATION_JSON)
  34. public AlertObject alertsByDateRange(@NotNull @Valid @QueryParam("startDate") ZonedDateTime startDate,
  35.                                                  @NotNull @Valid @QueryParam("endDate") ZonedDateTime endDate) { ... }

The above 2 parameters are both supposed to be required parameters. So I set the required = true. However, once I set them to required, I was no longer able to execute this API call through swagger. When I used Postman to call this function it worked perfectly. However, I can no longer use the swagger UI to test. I don't know why that is? I even tried setting the schema field for one of them (I thought that perhaps swagger needed to know how to validate) but that didn't help. So now, when I fill out those fields, swagger highlights them in red and refuses to execute this API call. Swagger for Java – 必填字段阻止执行 When I hover my mouse over the red box, it says "Required field is not provided".

I looked online but I cannot find a good set of examples of how to properly set required parameters in swagger for java, nor could I find an API that describes the nuances of the java version.

So my question is - how do I properly setup required parameters such that they are still executable through the swagger UI?

答案1

得分: 0

我找到了问题。

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

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

第二次是：

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

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

  1. parameters:
  2.   - name: startDate
  3.     in: query
  4.     description: Get historical alerts from this date. `startDate` should be in GMT and 24 hour Clock
  5.     required: true
  6.     schema:
  7.       type: string
  8.       format: date-time
  9.     example: 2020-07-15T15:57:00Z
  10.   ...
  11.   - name: startDate
  12.     in: query
  13.     required: true
  14.     schema:
  15.       type: string
  16.       format: date-time

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

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

一旦我移除了第二次声明，我就能够使用Swagger来测试我的API调用。

英文:

I figured out the issue.

If you notice in the code above, I declare the same parameter in swagger twice. The first time is:

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

And the second time is:

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

When I looked at the yaml, I saw this:

  1.  parameters:
  2.   - name: startDate
  3.     in: query
  4.     description: Get historical alerts from this date. `startDate` should be in
  5.       GMT and 24 hour Clock
  6.     required: true
  7.     schema:
  8.       type: string
  9.       format: date-time
  10.     example: 2020-07-15T15:57:00Z
  11.   ...
  12.   - name: startDate
  13.     in: query
  14.     required: true
  15.     schema:
  16.       type: string
  17.       format: date-time

The parameter appears twice as a result. And you can tell which is which, because the 1st parameter has a description and the second one does not.

(I think the underlying problem is that both are considered required but we are only able to fill out 1 parameter.)

Once I remove the second declaration I was then able to use swagger to test my API calls.

huangapple
  • 本文由 发表于 2020年7月22日 23:07:25
  • 转载请务必保留本文链接：https://go.coder-hub.com/63037440.html
  • java
  • swagger
  • swagger-2.0
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定