web-dev-qa-db-de.com

Swagger-Dokumentation für Spring Pageable-Schnittstelle

Ich habe einen Microservice mit Spring Boot entwickelt. Die Dokumentation für die API REST wurde mit Swagger erstellt. Einige REST -Ressourcen verwenden Spring-Konzepte, um die Paginierung kostenlos bereitzustellen. Unten ist ein Beispiel:

@RequestMapping(value = "/buckets", method = GET)
public PagedResources list(Pageable pageable, PagedResourcesAssembler assembler) {
    return bucketService.listBuckets(pageable, assembler);
}

Wenn ich die Swagger-Seite öffne, ist das folgende Formular für die Ressource verfügbar:

 enter image description here

Das Problem, das ich habe, ist, dass der auslagerungsfähige Parameter mit dem Inhaltstyp application/json erkannt wird und ich nicht weiß, wie ich einen Wert übergeben kann, um beispielsweise die Seitengröße zu ändern. Alle Werte scheinen ignoriert zu werden.

Können die Abfrageparameter als JSON-Objekt übergeben werden? oder ist es möglich, Swagger so zu konfigurieren, dass unabhängige Abfrageparameterfelder für in der Pageable-Schnittstelle enthaltene Getter erstellt werden? 

Bitte beachten Sie, dass ich Springfox mit Gradle verwende:

compile 'io.springfox:springfox-spring-web:2.3.1'
compile 'io.springfox:springfox-swagger2:2.3.1'
compile 'io.springfox:springfox-swagger-ui:2.3.1'
jsonspringrestswagger
16
Laurent

Dies ist ein bekanntes Problem mit Spring-Fox. Siehe Ausgabe # 755 . Basierend auf zdilas Kommentar 2 zu diesem Zeitpunkt besteht die Alternative darin, @ApiImplicitParams hinzuzufügen, was nicht ideal ist, aber funktioniert.

@ApiImplicitParams({
    @ApiImplicitParam(name = "page", dataType = "integer", paramType = "query",
            value = "Results page you want to retrieve (0..N)"),
    @ApiImplicitParam(name = "size", dataType = "integer", paramType = "query",
            value = "Number of records per page."),
    @ApiImplicitParam(name = "sort", allowMultiple = true, dataType = "string", paramType = "query",
            value = "Sorting criteria in the format: property(,asc|desc). " +
                    "Default sort order is ascending. " +
                    "Multiple sort criteria are supported.")
})

[Swagger UI showing @ApiImplicitParams for Pageable]

1https://github.com/springfox/springfox/issues/755

2https://github.com/springfox/springfox/issues/755#issuecomment-135059871

23
Vineet Bhatia

Vineet Bhatias Antwort mit @ApiImplicitParams sieht gut aus. Aber ich war mit einer Situation konfrontiert, in der @ApiIgnor und @ApiParam(hidden = true) nicht funktionieren und Sie immer noch den Assembler und die pagablen Parameter beobachten können. Ich habe dieses Problem durch Hinzufügen der nächsten Zeile behoben

docket.ignoredParameterTypes(Pageable.class, PagedResourcesAssembler.class);

auf die Docket-Bean in meiner SwaggerConfig.

5
Mykola Lavrenko

Aufbauend auf der Antwort von Vineet Bhatia können Sie die Lösung in eine benutzerdefinierte Anmerkung zur Wiederverwendbarkeit einpacken:

@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
@ApiImplicitParams({
    @ApiImplicitParam(name = "page", dataType = "int", paramType = "query", value = "Results page you want to retrieve (0..N)"),
    @ApiImplicitParam(name = "size", dataType = "int", paramType = "query", value = "Number of records per page."),
    @ApiImplicitParam(name = "sort", allowMultiple = true, dataType = "string", paramType = "query", value = "Sorting criteria in the format: property(,asc|desc). "
            + "Default sort order is ascending. " + "Multiple sort criteria are supported.") })
@interface ApiPageable {
}

Was kann dann so verwendet werden:

@ApiPageable
public Page<Data> getData(Pageable pageRequest) {
5
Sean Connolly

Antwort von Vineet Bhatia hat ein Validierungsproblem, wenn Sie nicht localhost ausführen. Für ganzzahlige Parameter wird argumentiert, dass sie nicht dem Json-Schema entsprechen.

Also habe ich Integer in String geändert:

    @ApiImplicitParams({
        @ApiImplicitParam(name = "page", dataType = "string", paramType = "query",
                value = "Results page you want to retrieve (0..N)"),
        @ApiImplicitParam(name = "size", dataType = "string", paramType = "query",
                value = "Number of records per page."),
        @ApiImplicitParam(name = "sort", allowMultiple = true, dataType = "string", paramType = "query",
                value = "Sorting criteria in the format: property(,asc|desc). " +
                        "Default sort order is ascending. " +
                        "Multiple sort criteria are supported.")
})
2
Evgeny Konurbaev

Für Leute, die dieses Problem im Jahr 2019 lösen möchten. Diese Konfiguration über springfox documentation funktioniert einwandfrei, außer Sie können keine Beschreibung für Parameter festlegen.

Code ist hier.

https://github.com/springfox/springfox/blob/ef1721afc4c910675d9032bee59aea8e75e06d27/springfox-data-rest/src/main/Java/springfox/documentation/spring/data/restonfiguration .Java

2
helsonxiao

Obwohl die Lösung mit den impliziten Parametern funktioniert, führt sie viel zusätzlichen, spröden Code ein. Am Ende haben wir folgende Lösung gewählt:

@GetMapping(value = "/")
public HttpEntity<PagedResources<Item>> getItems(
    @RequestParam(value = "page", required = false) Integer page,
    @RequestParam(value = "size", required = false) Integer size,
    PagedResourcesAssembler assembler) {
    Page<Item> itemPage = itemService.listItems(PageRequest.of(page, size, Sort.unsorted()));
    return new ResponseEntity<>(assembler.toResource(itemPage), HttpStatus.OK);
}

Wir übergeben eine PageRequest (die Pageable implementiert) an unseren Service, die eine Page zurückgibt. (alles von org.springframework.data.domain).

Der org.springframework.data.web.PagedResourcesAssembler wird automatisch über die Controller-Methode injiziert und ermöglicht das Zuordnen von Elementen zu org.springframework.hateoas.PagedResources.

Wir benötigten keine dynamische Sortierung, daher haben wir das weggelassen. Das Hinzufügen von Sortierungen ist mit einigen Herausforderungen verbunden, da springfox mit org.springframework.data.domain.Sort nicht Nice spielt.

0
Adriaan Koster