web-dev-qa-db-ja.com

Spring PageableインターフェースのSwaggerドキュメント

Spring Bootを使用してマイクロサービスを開発しました。 REST APIのドキュメントはSwaggerで作成されています。一部のRESTリソースは、Springの概念を使用してページネーションを無料で提供します。以下に例を示します。

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

Swaggerページを開くと、リソースで次のフォームを使用できます。

enter image description here

私が持っている問題は、ページング可能なパラメーターがcontent-typeapplication/jsonで検出され、変更する値を渡す方法がわからないことですたとえば、ページサイズ。すべての値は無視されるようです。

クエリパラメータをJSONオブジェクトとして渡すことは可能ですか？または、Pageableインターフェイスに含まれるゲッターの独立したクエリパラメータフィールドを生成するようにSwaggerを構成することは可能ですか？

私はGradleでSpringfoxを使用していることに注意してください：

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
21
Laurent

これは、Spring-Foxの既知の問題です。問題 ＃755 を参照してください。 zdilaのコメントに基づいて 2 現時点では、理想的ではないが機能する@ApiImplicitParamsを追加することもできます。

@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

28
Vineet Bhatia

Vineet Bhatiaの答えを基に、ソリューションを再利用性のためにカスタムアノテーションでまとめることができます。

@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 {
}

これは次のように使用できます：

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

_@ApiImplicitParams_を含むVineet Bhatiaの回答は問題ありません。しかし、_@ApiIgnor_と@ApiParam(hidden = true)が機能せず、アセンブラーとページング可能なパラメーターを観察できる状況に直面しました。次の行を追加してこの問題を修正しました

_docket.ignoredParameterTypes(Pageable.class, PagedResourcesAssembler.class);
_

SwaggerConfigのDocket Beanに。

8
Mykola Lavrenko

Vineet Bhatiaの回答には、localhostで実行していない場合の検証の問題があります。整数パラメータについては、jsonスキーマに対応していないと主張します。

そこで、整数を文字列に変更しました。

    @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

2019年にこの問題を解決したい人向け。 springfox documentation を介したこの設定は、パラメーターの説明を設定できない場合を除き、正常に機能します。

コードはこちらです。

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

2
helsonxiao

暗黙的なパラメーターを使用したソリューションは機能しますが、多くの余分で脆弱なコードが導入されます。最後に、次のソリューションを使用しました。

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

PageRequest（Pageableを実装する）をサービスに渡し、サービスはPageを返します。 （すべてorg.springframework.data.domain）。

org.springframework.data.web.PagedResourcesAssemblerは、コントローラーメソッドを介して自動的に挿入され、Itemsをorg.springframework.hateoas.PagedResources

動的な並べ替えは必要なかったため、省略しました。 springfoxはorg.springframework.data.domain.SortでNiceを再生しないため、並べ替えを追加するのにいくつかの課題があります。

0
Adriaan Koster