英文:
Swagger for java - the required field prevents execution
问题
I am using swagger with the following Maven dependency:
 <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.0.9</version>
    </dependency>
I wrote an API call as follows:
@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) { ... }
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:
 <dependency>
        <groupId>io.swagger.core.v3</groupId>
        <artifactId>swagger-jaxrs2</artifactId>
        <version>2.0.9</version>
    </dependency>
I wrote an API call as follows:
@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) { ... }
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 setup required parameters such that they are still executable through the swagger UI?
答案1
得分: 0
我找到了问题。
如果你注意到上面的代码,我在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,但我们只能填写一个参数。)
一旦我移除了第二次声明,我就能够使用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:
@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),
And the second time is:
@NotNull @Valid @QueryParam("startDate") ZonedDateTime startDate,
When I looked at the yaml, I saw this:
 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
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.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。


评论