我试图用Spring 4.3和Jackson 2.22.2来制作由Jersey-Spring 2.22.2组成的Swagger文档。
我正在使用的swagger包是：
<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编辑器中解析这个输出时，它会返回错误，我认为原因可能是它在“paramas”名称参数中创建了它的对象类型而不是模式。 我的观点是找出原因？ 是否有一些错误或错失了某些东西？
另外，在另一个端点上，有@FormDataParam是@ApiModel注解的pojo模型对象。 这是通过类型为'ref'的swagger翻译的，但它不会给用户任何其他线索，说明该对象是什么或者它应该包含哪些字段。 在Swagger-UI中，我只看到'undefined'作为参数类型。 这并没有太多的信息。 我需要做什么才能看到对象的结构，并提供它的json定义作为例子来尝试用户界面？ 谢谢
I am trying to make swagger document my API composed of Jersey-spring 2.22.2 with Spring 4.3 and Jackson 2.22.2.
The swagger package I'm using is:
<dependency> <groupId>io.swagger</groupId> <artifactId>swagger-jersey2-jaxrs</artifactId> <scope>compile</scope> <version>1.5.12</version> </dependency>one of endpoint declaration:
@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(); }and this is how the generated json looks like for this endpoint:
"/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" } } } }when I try to parse this output in swagger editor it returns error back, and I think the reason might be that in "paramas" names parameter it has created its type of object instead of schema. My point here is to find out why? Is it some bug in swagger or it's me that missed something?
Also, on the another endpoint I have, there is @FormDataParam that is an pojo model object annotated with @ApiModel. This is translated by swagger as of type 'ref' but it doesn't gives user any other clue of what this object is or which fields it should contain. In Swagger-UI I see just 'undefined' as param type. This is not much informing. What I need to do in order to see the object's structure and to supply it's json definition as an example to try in ui? Thanks
最满意答案
这个答案包含了最终Swagger规范应该是什么样子的例子，但我不知道如何使用Swagger @annotations来表达它。 希望这给你一些想法。
在Swagger 2.0中，没有简单的方法在请求体中拥有文件+对象 - 形式参数可以是原始值，数组和文件而不是对象，而且体参数支持对象但不支持文件（尽管您可以尝试将文件表示为type: string - 更多在下面）。
下一个版本OpenAPI规范3.0（在编写本文时是RC）将支持包含文件+对象的请求主体 - 请检查此示例 。 我认为@annotations也会更新以支持这一点。
现在你有几个选择。
1）一种可能的方法是将文件内容作为二进制字符串传递给身体参数。 您的API规范如下所示：
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: string2）另一种可能的方式是将元数据名称和值作为单独的数组发送，因此您将拥有3个表单参数：文件，键名称数组和键值数组。 这与以下类似：
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: stringThis answer contains examples of how the final Swagger spec should look like, but I don't know how to express that using Swagger @annotations. Hope this gives you some ideas anyway.
In Swagger 2.0, there is no straightforward way to have file + object in request body – form parameters can be primitive values, arrays and files but not objects, and body parameters support objects but not files (although you can try representing files as type: string – more on that below).
The next version, OpenAPI Specification 3.0 (which is RC at the time of writing) will support request body containing files + objects – check this example. I assume @annotations will be updated to support that too.
For now you have a couple of options.
1) One possible way is to pass the file contents as a binary string as part of the body parameter. Your API spec would look like:
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: string2) Another possible way is to send the metadata names and values as separate arrays, so you would have 3 form parameters: file, array of key names, and array of key values. This is analog to:
curl -F "file=@foo.zip" -F "metadata_keys=description,author" -F "metadata_values=A ZIP file,Helen" https://api.example.comYour API spec would look like this:
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更多推荐
发布评论