Swagger 1.5 未生成有效的 JSON 描述

Question

我正在尝试制作由 Jersey-spring 2.22.2 和 Spring 4.3 和 Jackson 2.22.2 组成的 API 的 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 editor 中解析此输出时，它 returns 返回错误，我认为原因可能是在 "paramas" names 参数中它创建了它的对象类型而不是模式。我的意思是找出原因？是大摇大摆的错误还是我错过了什么？

此外，在我的另一个端点上，有一个 @FormDataParam，它是一个用 @ApiModel 注释的 pojo 模型对象。这是由 'ref' 类型的 swagger 翻译的，但它不会向用户提供有关此对象是什么或它应包含哪些字段的任何其他线索。在 Swagger-UI 中，我只看到 'undefined' 作为参数类型。这没有太多信息。我需要做什么才能看到对象的结构并提供它的 json 定义作为在 ui 中尝试的示例？谢谢

Answer 1

此答案包含最终 Swagger 规范的示例，但我不知道如何使用 Swagger @annotations 来表达它。希望这能给你一些想法。

在Swagger 2.0中，没有直接的方式在请求体中有文件+对象——表单参数可以是原始值、数组和文件但不能是对象，body参数支持对象而不是文件（虽然你可以试试将文件表示为 type: string – 更多内容见下文）。

下一版本 OpenAPI 规范 3.0（撰写本文时为 RC）将支持包含文件 + 对象的请求正文 – 检查 this example。我假设@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: string

2) 另一种可能的方法是将元数据名称和值作为单独的数组发送，因此您将有 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: string

Swagger 1.5 未生成有效的 JSON 描述

Swagger 1.5 not generating valid JSON description

java

tomcat7

swagger

jersey-2.0

swagger-ui