8

I use this library for generation documentation:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.0</version>
</dependency>

I have this controller:

@RestController
public class TestController {

    @GetMapping("/test{hz}")
    public String test(@PathVariable(value = "hz", required = false) String hz) {
        return "test";
    }
}

But I get this documentation:

enter image description here

Why required = false doesn't work?

I tried this:

@RestController
public class TestController {

    @GetMapping("/test{hz}")
    public String test(
            @Parameter(description = "foo", required = false)
            @PathVariable(value = "hz", required = false) String hz) {
        return "test";
    }
}

It doesn't work too

EDIT: (Answer for @Helen comment) - Of course I know about this:

@RestController
public class TestController {

    @GetMapping(value = {"/test", "/test{hz}"})
    public String test(
            @Parameter(description = "foo", required = false)
            @PathVariable(value = "hz", required = false) String hz) {
        return "test";
    }
}

And I tried this:

@PathVariable(value = "hz", required = false) Optional<String> hz

It makes documentation worse. so I didn't add this code. With {"/test", "/test{hz}"} It looks like this:

enter image description here

Pavel Petrashov
  • 1,073
  • 1
  • 15
  • 34
  • 2
    Path parameter are always required. To have an optional path parameter, you'll need to [define two paths](https://stackoverflow.com/a/35030135/113116) - with and without that parameter. – Helen Nov 20 '20 at 14:33
  • @ Helen I added more information to my question. – Pavel Petrashov Nov 20 '20 at 16:03
  • `@PathVariable` MUST have `required = true`, path parameters cannot be marked optional. You need to define 2 separate methods - one with the `hz` parameter and one without it. – Helen Nov 20 '20 at 17:14
  • @Helen it looks strange. Why do you so categorical? Spring annotation `public @interface PathVariable` has a parameter `boolean required() default true;` and I can set `required == false` and it works in Spring. Swagger annotation `public @interface Parameter` has `boolean required() default false;` Why have to I use 2 separate methods? Spring allows me use one method `@GetMapping(value = {"/test", "/test{hz}"})`. Do you consider that library(swagger) must dictate rules? – Pavel Petrashov Nov 21 '20 at 19:12
  • [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#user-content-parameterrequired) states that path parameters MUST have `required: true`. They cannot be optional. Maybe @PathVariable with required=false is an option for other API description formats, but it's not compatible with OpenAPI. You need two separate methods because the method for `/test{hz}` must have a required path parameter and the method for `/test` must have no parameters. – Helen Nov 23 '20 at 10:30
  • @Helen I have known it since your first answer. I just want to say that it is uncomfortable. It is bad practice to change API signature only for OpenAPI Specification – Pavel Petrashov Nov 23 '20 at 11:02
  • There's an existing feature request in the OpenAPI Specification repo to add [support for optional path parameters](https://github.com/OAI/OpenAPI-Specification/issues/622), maybe this will be supported in the future. – Helen Nov 23 '20 at 13:17
  • Although the request is open, I think the sole purpose of having a path parameter as opposed to query parameter is the fact that it is not optional. Also, given the fact that path parameters can appear in between the path, in which case a missing value for it might lead to ambiguity. – Debargha Roy Nov 25 '20 at 18:13

1 Answers1

1

This is conform to the OpenAPI specification.

Each path parameter must be substituted with an actual value when the client makes an API call. In OpenAPI, a path parameter is defined using in: path. The parameter name must be the same as specified in the path. Also remember to add required: true, because path parameters are always required.

You can have a look at the documentation:

brianbro
  • 4,141
  • 2
  • 24
  • 37