Getting Swagger error when specifying "file" as response type

[cwarny]

My API can return either JSON or compressed files. I set the following top-level producesspec:

produces:
  - application/json
  - application/x-gzip

However, when on one of my endpoints I specify the following:

responses:
  "200":
    description: Success
      schema:
        type: file

I get the following Swagger Error: Validation error: enum, with an error path pointing to the type: file above.

The specs are not entirely clear to me as to how I should format an endpoint that returns a compressed file, but the above was the result of my understanding. Is this a bug or was my understanding incorrect? If the latter, could someone enlighten me?

[webron]

There's a bug in the json schema which doesn't allow file as a response (and both swagger-tools and swagger-editor depend on it). There isn't an open issue about it yet, so let's keep it here (I have it in my own todo list).

But to put your mind at ease - your declaration is indeed correct.

If you have any suggestions on how to make the spec clearer with regards to it, I'd love the input. I'm in the process of adding the examples, clarifications, and fixing the json schema, so the feedback would be great at this point.

[cwarny]

Thanks. I think the spec is clear enough if it goes with an example. So my only suggestion would be to add an example, but I see that's already flagged as a TODO.

[nickretallack]

Oops, sorry, I created an issue over there. Here's my example schema btw:

swagger: '2.0'
info:
  version: "0.0.0"
  title: Example
paths:
  /test:
    get:
      responses:
        200:
          description: OK
          schema:
            type: file

This seems like the sort of bug that will affect virtually everybody. I'm currently working around it by deleting the schema from any routes that serve up files as responses.

[nickretallack]

I created a pull request that should handle this.

#293

Not sure how to test it or try it in the editor though.

[webron]

@nickretallack - Thanks for the PR but I'm not going to merge it yet. Changing the schema is a bit delicate as it affects several tools, and I'm going to do a bulk update rather than several small ones.

If you're looking to solve the issue for yourself for now, you should look into swagger-tools on which the editor depends on - @whitlockjc may be able to assist there.

[davequick]

👍 on this - ran into it today and was like - of course it does "file" as a return type... nope... ended up on this thread - glad someone already submitted PR, next time you suck in changes in your batch, please do include this. :-)

[ThomasBarnekow]

Is there any progress on this? "file" is still not supported.

[webron]

This should be fixed in the schema now.

[rkyoku]

I still get this error using editor.swagger.io:

0: Object
    code:  "ENUM_MISMATCH"
    message:  "No enum match for: file"
    path: Array [2]
        0:  "schema"
        1:  "type"

And my schema file:

      responses:
        '200':
          schema:
            type: file
          headers:
            Content-type:
              type: string
              description: text/csv; charset=utf-8
            Content-Disposition:
              type: string
              description: attachment; filename=myfile.csv
          description: Export data into a CSV file

Should I do something in particular to benefit from the bugfix?

My current workaround is to use type string

[webron]

It will take a bit for the schema updates to propagate to the different projects.

[rkyoku]

Ok thank you for the fast answer @webron, I can indeed totally live with(out) it for now :) sorry for the disturbance, I was assuming it was instantaneous