springdoc-openapi-ui + swagger nie rozumieją @PathVariable required = false flag

Nov 20 2020

Używam tej biblioteki do generowania dokumentacji:

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

Mam ten kontroler:

@RestController
public class TestController {

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

Ale dostaję tę dokumentację:

Dlaczego required = falsenie działa?

Próbowałem tego:

@RestController
public class TestController {

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

To też nie działa

EDYCJA : (Odpowiedź na komentarz @Helen) - Oczywiście wiem o tym:

@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";
    }
}

I spróbowałem tego:

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

To pogarsza dokumentację. więc nie dodałem tego kodu. Z {"/test", "/test{hz}"}Wygląda to tak:

Odpowiedzi

1 brianbro Dec 01 2020 at 20:52

Jest to zgodne ze specyfikacją OpenAPI.

Każdy parametr ścieżki należy zastąpić rzeczywistą wartością, gdy klient wykonuje wywołanie interfejsu API. W OpenAPI parametr ścieżki jest definiowany za pomocą in: path. Nazwa parametru musi być taka sama, jak określona w ścieżce. Pamiętaj również, aby dodać required: true , ponieważ parametry ścieżki są zawsze wymagane.

Możesz zajrzeć do dokumentacji:

  • https://swagger.io/docs/specification/describing-parameters/#path-parameters