Describing PUT application/octet-stream in Swagger / Editor

[Gunnar Wagenknecht]

Hi,

I've just started working with Swagger and documenting an existing API. One piece there is a direct file upload functionality via PUT. I wonder how to express that in swagger-editor because I'm getting an error.

Here is the sample yaml:

swagger: '2.0'

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

I think this should be ok according to the spec. But swagger-editor gives me:

Data does not match any schemas from 'oneOf'

Any ideas?

Thanks!

-Gunnar

[tony tam]

Hi, the supported file upload mechanism can be seen here:

http://petstore.swagger.io/v2/swagger.yaml

look at /pet/{petId}/uploadImage

That requires multipart/form-data with a form element, which is more common for web-based file uploads.  I do know there are many techniques to upload files, but this is what the spec (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) supports.

[Gunnar Wagenknecht]

Hi,

> Am 11.04.2015 um 22:44 schrieb tony tam <feh...@gmail.com>:
>
> look at /pet/{petId}/uploadImage
>
> That requires multipart/form-data with a form element, which is more common for web-based file uploads. I do know there are many techniques to upload files, but this is what the spec (https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) supports.

Thanks for the link! I found a lot examples like that and I know the swagger-ui only supports a limited set of upload functionality.

If I read the spec correctly, it should actually support a broader that of upload functionality. Also the one spec'ed below should be fine from a spec perspective.

paths:
/upload:
put:
summary: Upload
parameters:
- name: file
in: body
description: the attachment content
required: true
schema:
type: file
consumes:
- application/octet-stream
responses:
200:
description: the upload was successful

Thus, I believe that I hit a limitation within swagger-editor. That's what I need to confirm. Is there a way to validate that technically by "verifying" the json swagger definition on the command line, i.e. outside of swagger-editor?

-Gunnar

[Ron Ratovsky]

Unfortunately, it's a limitation of the spec. If you read the description here - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterType - you'll see that using type "file" limits you to specific mime types and parameter type.

We have several open tickets as suggestions for the next version involving files - https://github.com/swagger-api/swagger-spec/issues/222, https://github.com/swagger-api/swagger-spec/issues/254 and https://github.com/swagger-api/swagger-spec/issues/303 (roughly).

It would be great if you could open a ticket on that as well, giving as many details as possible (assume we don't know how application/octet-stream works), with your use case, links to specifications, library references that support it and existing APIs you know that use it. You don't have to include all that, but the more details we have, the easier it would be for us to bring support for it in the future. Once you open the ticket, I'm sure more people would join with their suggestions and votes for it.

-Gunnar

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[Gunnar Wagenknecht]

> Am 12.04.2015 um 07:53 schrieb Ron Ratovsky <r...@swagger.io>:
>
> Unfortunately, it's a limitation of the spec. If you read the description here - https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#parameterType - you'll see that using type "file" limits you to specific mime types andparameter type.

That's what I'm not sure about. Right above the table is a statement say that this only applies if 'in is any value other than "body"'. Right above is a table when 'in' is "body" and that only talks about schema being a fixed field. Maybe the spec means to apply the limitation globally. But they it's written leads me to believe that this limitation only applies if the parameter is not in body.

-Gunnar

[Ron Ratovsky]

When the parameter is "in" body, then there's no type, but a Schema Object. For a Schema Object, "file" is not a valid "type" so you can't use that combination.

-Gunnar

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Gunnar Wagenknecht]

Thanks for clarification!

Filed:
https://github.com/swagger-api/swagger-spec/issues/326

-Gunnar

--
Gunnar Wagenknecht
gun...@wagenknecht.org, http://guw.io/

> You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/4ANfdyxEi_k/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.