1

In Flasgger, I'm trying to create documentation for route which accepts uploaded files. However, despite sticking to the specification, I cannot display file selector in Flasgger UI.

I'm using latest (as of today) flasgger==0.9.1 running OpenAPI 3 specs (as in "openapi": '3.0.0') and I saw this commit in Swagger-UI, that enables file selectors for POST file requests.

I know similar questions were asked before, but none of them related to OAS version 3.

My code snippet is below:

Upload a file
Returns ID of uploaded file
---

tags:
- name: "attachments"
schemes:
- "http"

consumes:
- application/octet-stream
produces:
- application/json

requestBody:
  content:
    application/octet-stream:
      schema:
        type: file
        format: binary

responses:
  200:
    ... etc

And I get just an empty block input in Flasgger UI. Is it possible Flasgger does not support it even though Swagger-UI does (I thought it's built on top of it)? Or the syntax is wrong?

adamczi
  • 343
  • 1
  • 7
  • 24

1 Answers1

2

You are mixing OpenAPI 2.0 and 3.0 syntax. In OAS3, files are described as binary strings, that is type: string and not type: file. Also, the consumes, produces and schemes keywords are not used in OAS3.

Try the following:

Upload a file
Returns ID of uploaded file
---

tags:
- attachments

requestBody:
  content:
    application/octet-stream:
      schema:
        type: string   # <-------
        format: binary

responses:
  '200':
    description: OK
    content:
      application/json:
        schema:
          # ... etc

Note that OAS3 file upload requires Swager UI 3.16.0+ but Flassger 0.9.1 is bundled with UI 3.14.2 and there seems to be no way to update the bundled Swagger UI. This possibility will be added in the next update, Flassger 0.9.2:

https://github.com/rochacbruno/flasgger#externally-loading-swagger-ui-and-jquery-jscss

So you'll need to wait for Flassger 0.9.2.


I also recommend that you check the generated OpenAPI file for syntax errors using the Swagger Editor, because syntax errors might cause incorrect parsing/rendering. This answer explains how to export your OpenAPI file from Swagger UI so that you can use it elsewhere.

Helen
  • 87,344
  • 17
  • 243
  • 314
  • Hi, thanks for your answer and syntax advice. However, this way I just get "string" string inside proposed payload, instead of file selector: https://i.imgur.com/eiZ8P4H.png – adamczi Oct 09 '18 at 10:21
  • Which version of Swagger UI do you use? Open the browser dev tools > Console tab and evaluate the `versions` variable. OAS3 file upload was added in 3.16.0 I think. – Helen Oct 09 '18 at 10:43
  • I'm not sure, but [here is a swagger-ui.js file](https://github.com/rochacbruno/flasgger/blob/master/flasgger/ui3/static/swagger-ui.js) being loaded and I can find a string `{version:"2.5.6"}` in there. Looks like Flasgger uses OAS 3 and Swagger-UI 2? – adamczi Oct 09 '18 at 10:50
  • It's UI 3.x for sure. Please check the version in the browser console as shown here: https://i.stack.imgur.com/WX64V.png – Helen Oct 09 '18 at 11:04
  • It's an old version. You need to update it with the latest version from https://github.com/swagger-api/swagger-ui/tree/master/dist. Flassger 0.9.2 lets you load Swagger UI JS/CSS [from a custom location](https://github.com/rochacbruno/flasgger#externally-loading-swagger-ui-and-jquery-jscss) instead of using the bundled version. You can also open an issue in the Flassger repository and ask them to update the bundled Swagger UI to make use of the latest UI improvements. – Helen Oct 09 '18 at 11:24
  • 1
    As the latest available version of Flasgger is `0.9.1` (docs are probably already prepared for the next release), testing it doesn't result in any change. Also tried manually substitute JS/CSS files, but this returned an error while loading Flassger site. Anyway, seems like I have to wait for `0.9.2`, please post your comment as an answer, so I can accept it! Thanks for help – adamczi Oct 09 '18 at 11:54