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?
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.