Swagger 1.5未生成有效的JSON描述

Question

我正在尝试大摇大摆地记录我的 API，该 API 由泽西Spring 2.22.2 与Spring 4.3 和杰克逊 2.22.2 组成。

我使用的swagger软件包是:

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

endpoint声明之一：

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

这就是此endpoint生成的 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”name参数中，它创建了它的对象类型而不是模式。我的重点是找出原因？是大摇大摆的小虫还是我错过了什么？

此外，在我的另一个endpoint上，有@FormDataParam，它是一个用@ApiModel注释的pojo模型对象。这被swagger翻译为“ref”类型，但它没有给用户任何其他线索来说明这个对象是什么或者它应该包含哪些字段。在Swagger-UI中，我只看到“未定义”作为参数类型。这没有太多信息。我需要做什么才能看到对象的结构，并提供它的json定义作为示例在用户界面中尝试？谢谢

Answer 1

这个答案包含最终Swagger规范应该是什么样子的示例，但是我不知道如何使用Swagger@注释来表达它。希望这能给你一些想法。

在Swagger 2.0中，没有直接的方法在请求体中包含文件对象——表单参数可以是原始值、数组和文件，但不是对象，而体参数支持对象，但不是文件(尽管您可以尝试将文件表示为< code > 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: 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