Swagger 1.5가 유효한 JSON 설명을 생성하지 않음

Question

스프링 API 2.92.2와 Spring 4.3 및 Jackson 2.22.2로 구성된 내 API를 쓸데없는 문서로 만들려고합니다. 엔드 포인트 선언의

<dependency> 
      <groupId>io.swagger</groupId> 
      <artifactId>swagger-jersey2-jaxrs</artifactId>       
      <scope>compile</scope> 
      <version>1.5.12</version> 
</dependency> 

일 :

내가 사용하고있어 자신감 패키지는

@POST 
    @ApiOperation(
      value = "creates folder hierarchy type client|lead", 
      notes = "creates folder hierarchy type client|lead" 
    ) 
    @ApiResponses(value = { 
      @ApiResponse(code = 200, message = "creation successfull") 
    }) 
    @Path("create_type") 
    @Consumes(MediaType.MULTIPART_FORM_DATA) 
    public Response createHierarchy(
      @ApiParam(value = "hierarchy type", required = true) @NotNull @FormDataParam("type") EHierarchyType hierarchyType, 
      @ApiParam(value = "parametric part of the hierarchy", required = true) @NotNull @FormDataParam("params") Map<String, Folder2> folderMap 
    ) throws ItemExistsException, AccessDeniedException, PathNotFoundException, WebserviceException, RepositoryException, DatabaseException, ExtensionException, AutomationException, UnknowException, IOException, UserQuotaExceededException, LockException, VersionException { 
     StopWatch stopWatch = new StopWatch(); 

     folderCtrl.createHierarchy(folderMap, hierarchyType); 
     logger.info("create hierarchy took: " + stopWatch.getElapsedTime()); 

     return Response.ok().build(); 
    } 

이 생성 된 JSON이 엔드 포인트에 대해 같은 모습입니다 :

"/folder/create_type" : { 
     "post" : { 
     "tags" : [ "folder" ], 
     "summary" : "creates folder hierarchy type client|lead", 
     "description" : "creates folder hierarchy type client|lead", 
     "operationId" : "createHierarchy", 
     "consumes" : [ "multipart/form-data" ], 
     "parameters" : [ { 
      "name" : "type", 
      "in" : "formData", 
      "description" : "hierarchy type", 
      "required" : true, 
      "type" : "string", 
      "enum" : [ "CLIENT", "LEAD" ] 
     }, { 
      "name" : "params", 
      "in" : "formData", 
      "description" : "parametric part of the hierarchy", 
      "required" : true, 
      "type" : "object" 
     } ], 
     "responses" : { 
      "200" : { 
      "description" : "creation successfull" 
      } 
     } 
     } 
    } 

swagger editor에서이 출력을 구문 분석하려고하면 오류가 다시 반환되며 그 이유는 "paramas"names 매개 변수에서 스키마 대신 객체 유형을 생성했을 수도 있습니다. 이유는 무엇입니까? 흔들리는 부분에 버그가 있습니까? 아니면 놓친 부분이 있습니까?

또한 다른 끝 점에는 @ApiModel로 주석 된 pojo 모델 객체 인 @FormDataParam이 있습니다. 이것은 'ref'유형으로 swagger에 의해 번역되었지만 사용자에게이 객체가 무엇인지 또는 어떤 필드가 포함되어야하는지에 대한 다른 단서를 제공하지 않습니다. Swagger-UI에서는 param 유형으로 '정의되지 않음'만 표시됩니다. 이것은별로 알려주지 않습니다. 객체의 구조를보고, json 정의를 예제로 제공하기 위해 내가해야 할 일은 무엇입니까? 감사합니다.

Answer 1

이 답변에는 최종 Swagger 사양이 어떻게 표시되는지에 대한 예제가 포함되어 있지만 Swagger @ 주석을 사용하여 표현하는 방법을 알지 못합니다. 어쨌든이 아이디어가 도움이되기를 바랍니다.

자신감 2.0, 요청 본문에 파일 + 개체가 할 간단한 방법이 없다 - 당신이 시도 할 수 있지만 (기본 값, 배열 및 파일이 아닌 개체 및 신체 매개 변수 지원 객체가 아닌 파일이 될 수 폼 매개 변수 파일을 대표하는 파일은 type: string –입니다.

다음 버전 인 OpenAPI 사양 3.0 (작성 당시 RC)은 파일과 개체가 포함 된 요청 본 + – 체크 this example을 지원합니다. 나는 @ 주석이 그것을 지원하도록 업데이트 될 것이라고 생각한다.

지금은 몇 가지 옵션이 있습니다.

1) 가능한 한 가지 방법은 파일 내용을 body 매개 변수의 일부로 2 진 문자열로 전달하는 것입니다.

paths: 
    /something: 
    post: 
     consumes: 
     - application/json 
     parameters: 
     - in: body 
      name: body 
      required: true 
      schema: 
      $ref: '#/definitions/FileWithMetadata' 
     ... 

definitions: 
    FileWithMetadata: 
    type: object 
    required: [file_data] 
    properties: 
     file_data: 
     type: string 
     format: binary # or format: byte 
     metadata: 
     type: object 
     additionalProperties: 
      type: string 

2) 또 다른 가능한 방법은 별도의 배열과 같은 메타 데이터 이름과 값을 전송하는 것입니다, 그래서 당신은 3 형식 매개 변수 것 : 같은 귀하의 API 사양이 보일 것 파일, 키 이름의 배열과 키의 배열을 값. 이는 아날로그에 :

curl -F "file=@foo.zip" -F "metadata_keys=description,author" -F "metadata_values=A ZIP file,Helen" https://api.example.com 

과 같을 것이다 당신의 API 사양 :

paths: 
    /something: 
    post: 
     consumes: 
     - multipart/form-data 
     parameters: 
     - in: formData 
      name: file 
      type: file 
      required: true 
     - in: formData 
      name: metadata_keys 
      type: array 
      items: 
      type: string 
     - in: formData 
      name: metadata_values 
      type: array 
      items: 
      type: string