[SPRING] Spring Pageable 인터페이스에 대한 Swagger 문서

Spring Pageable 인터페이스에 대한 Swagger 문서

스프링 부트를 사용하여 마이크로 서비스를 개발했습니다. REST API에 대한 문서는 Swagger로 작성되었습니다. 일부 REST 리소스는 페이지 개념을 제공하기 위해 Spring 개념을 사용한다. 아래는 그 예입니다 :

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

Swagger 페이지를 열면 다음 양식을 리소스에 사용할 수 있습니다.

내가 가진 문제는 pageable 매개 변수가 content-type application / json으로 감지되어 예를 들어 페이지 크기를 변경하는 값을 전달하는 방법을 모른다는 것입니다. 모든 값은 무시 된 것 같습니다.

쿼리 매개 변수를 JSON 객체로 전달할 수 있습니까? 또는 Pageable 인터페이스에 포함 된 getter에 대한 독립 쿼리 매개 변수 필드를 생성하도록 Swagger를 구성 할 수 있습니까?

Springfox with Gradle을 사용하고 있습니다.

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'

해결법

1. ==============================

   1.이것은 Spring-Fox의 알려진 문제점입니다. 이슈 # 755를 참조하십시오. 이 시점에서 zdila의 의견을 바탕으로 대안은 @ApiImplicitParams를 추가하는 것입니다. 이상적이지는 않지만 작동합니다.

   이것은 Spring-Fox의 알려진 문제점입니다. 이슈 # 755를 참조하십시오. 이 시점에서 zdila의 의견을 바탕으로 대안은 @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.")
   })
   

   [

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

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

2. ==============================

   2.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) {
   

3. ==============================

   3.Vineet Bhatia의 @ApiImplicitParams에 대한 답변이 정상적으로 보입니다. 하지만 @ApiIgnor 및 @ApiParam (hidden = true)이 작동하지 않고 asembler 및 pageable 매개 변수를 관찰 할 수있는 상황에 직면했습니다. 다음 줄을 추가하여이 문제를 해결했습니다.

   Vineet Bhatia의 @ApiImplicitParams에 대한 답변이 정상적으로 보입니다. 하지만 @ApiIgnor 및 @ApiParam (hidden = true)이 작동하지 않고 asembler 및 pageable 매개 변수를 관찰 할 수있는 상황에 직면했습니다. 다음 줄을 추가하여이 문제를 해결했습니다.

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

   내 SwaggerConfig의 Docket 빈에.

4. ==============================

   4.Vineet Bhatia의 답변은 localhost를 사용하지 않을 때 유효성 검사 문제가 있습니다. 그것은 json 스키마에 해당하지 않는 정수 매개 변수를 주장합니다.

   Vineet Bhatia의 답변은 localhost를 사용하지 않을 때 유효성 검사 문제가 있습니다. 그것은 json 스키마에 해당하지 않는 정수 매개 변수를 주장합니다.

   그래서 integer를 string으로 변경했습니다.

       @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.")
   })
   

5. ==============================

   5.2019 년에이 문제를 해결하려는 사람들을 위해. springfox 문서를 통한이 설정은 매개 변수에 대한 설명을 설정할 수 없다는 점을 제외하고는 잘 작동합니다.

   2019 년에이 문제를 해결하려는 사람들을 위해. springfox 문서를 통한이 설정은 매개 변수에 대한 설명을 설정할 수 없다는 점을 제외하고는 잘 작동합니다.

   코드는 여기에 있습니다.

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

6. ==============================

   6.암시 적 매개 변수가있는 솔루션이 작동하기는하지만 많은 부수적 인 코드가 추가됩니다. 결국 우리는 다음 솔루션으로갔습니다.

   암시 적 매개 변수가있는 솔루션이 작동하기는하지만 많은 부수적 인 코드가 추가됩니다. 결국 우리는 다음 솔루션으로갔습니다.

   @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을 구현)가 우리의 서비스에 전달되어 페이지를 반환합니다. (all from org.springframework.data.domain).

   org.springframework.data.web.PagedResourcesAssembler는 컨트롤러 메소드를 통해 자동으로 주입되며 Item을 org.springframework.hateoas.PagedResources에 매핑 할 수 있습니다.

   동적 정렬을 요구하지 않았으므로 생략했습니다. springfox가 org.springframework.data.domain.Sort와 함께 훌륭하게 작동하지 않기 때문에 정렬을 추가하는 데 몇 가지 문제점이있다.

from https://stackoverflow.com/questions/35404329/swagger-documentation-for-spring-pageable-interface by cc-by-sa and MIT license