Question

我试图制作一个swagger文件，我的API由Jersey-spring 2.22.2和Spring 4.3以及Jackson 2.22.2组成。

我正在使用的招摇包是：

<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参数中它创建了它的对象类型而不是schema。我的观点是找出原因？这是一个招摇的错误，还是我错过了什么？

另外，在我的另一个端点上，有@FormDataParam是一个用@ApiModel注释的pojo模型对象。这是由swagger转换为类型'ref'，但它没有给用户任何其他线索，说明这个对象是什么或它应该包含哪些字段。在Swagger-UI中，我将'undefined'视为param类型。这没有多少信息。我需要做些什么来查看对象的结构并提供它的json定义作为在ui中尝试的示例？感谢

Answer 1

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

在Swagger 2.0中，没有直接的方法在请求体中包含文件+对象 - 表单参数可以是原始值，数组和文件但不是对象，而body参数支持对象但不支持文件（尽管您可以尝试表示文件如type: string - 更多关于以下内容。）

下一个版本，OpenAPI规范3.0（在撰写本文时为RC）将支持包含文件+对象的请求正文 - 检查this example。我认为@annotations也会更新以支持它。

现在你有几个选择。

1）一种可能的方法是将文件内容作为二进制字符串传递，作为body参数的一部分。您的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描述

1 个答案: