Allow file upload support using other mime types

[guw]

APIs allow for many different ways of uploading files. I'd like to be able to document the following in Swagger.

swagger: '2.0'

info:
  title: File Put Sample
  version: "1.0.0"
paths:
  /attachments/{name}:
    put:
      summary: Upload
      parameters:
        - name: name
          in: path
          description: the name of an attachment
          required: true
          type: string
        - name: content
          in: body
          description: the attachment content
          required: true
          schema:
            type: file
      consumes:
        - application/octet-stream
      responses:
        200:
          description: the upload was successful

This basically describes an API that can PUT file content onto a specific url. By setting consumes to other mime-typed then application/octet-stream (eg., image/png) it's also possible to express what content must be uploaded.

[BigSocial]

👍 for both PUT and POST

Java/Jersey code like this...

@POST
@Path("/{transformId}.bin")
@Consumes({MediaType.APPLICATION_OCTET_STREAM})
@Produces({ MediaType.APPLICATION_JSON })
@ApiOperation(
        value = "Starts a Job on the uploaded file",
        response = Job.class)
public Response runTransformRaw(
   @ApiParam(value = "Id of the transform", required = true)
   @PathParam("transformId") final String id,
   @ApiParam(value = "File to upload", required=true) InputStream inputStream) {
    return runTransformFromInputStream(id, inputStream);
}

...should generate a Parameter Object something like this...

{
name: "file",
in: "body",
description: "File to upload",
required: true,
type: "file"
}

...which Swagger UI and Sawgger Codegen should understand as the file being the entire binary body per RFC 2046 section 4.5.1. The justification for this is that it's likely to perform better than using multipart/form-data for high volume file transfer to a REST API.

[mohsen1]

also PATCH

[webron]

Umm, the issue isn't with the method, is with the mime type. There's no problem with put/post/patch/get/options/whatever for file uploads. Swagger doesn't care about that.

[BigSocial]

@webron yeah, the focus should have been in an Operation Object where consumes is application/octet-stream.

[webron]

It's time to change the title.

[webron]

We just finalized some discussion over in #50, so I'd like to propose a workaround for this issue.

In general, perhaps we shouldn't have gone with the file type anyways and need to provide better support for binary data transfer in general.

Based on #50, you should be able to use "type": "string", "format": "binary" instead of file type to overcome it.

[BigSocial]

So I'm a little confused about the implications of all this. If I may be concrete for a minute.

This code...

@POST
@Path("/bin")
@Consumes({MediaType.APPLICATION_OCTET_STREAM})
@Produces({MediaType.APPLICATION_JSON})
@ApiOperation(
        value = "Create a new Source from an uploaded file. This version expects the file as the raw contents of the request.",
        response = Source.class
        )
public Response makeSourceRaw(
        @ApiParam(value = "A file", required = true) InputStream inputStream
        )

...works perfectly (i.e. it allows access to the unencoded body) but currently generates this Swagger 2.0...

parameters: [
    {
        in: "body",
        name: "body",
        description: "A file",
        required: true,
        schema: {
             $ref: "#/definitions/InputStream"
        }
    }
]

...this, reasonably useless, Swagger UI...

...and generates a Java client that treats InputStream as if it were part of my model (i.e. creates a io.swagger.client.model.InputStream class), not an important concept in Java/Jersey, forcing me to hack the generated output to make it work.

Does "type": "string", "format": "binary" somehow magically fix this?

Is there any way right now to make Swagger (core, UI, codegen, etc.) understand that an InputStream param should be treated as a "raw" file upload?

[webron]

@BigSocial - I believe there isn't a solution for it yet in swagger-core, and it would be great if you could open an issue there so we'd handle it.

[BigSocial]

@webron Sorry, missed your initial response. Issue added to swagger-core.