Swagger 1.5 not generating valid JSON description

Question

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

Answer 1

This 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: string

2) 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.com

Your 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