Flasgger POST 路由中的文件上传选择器

Question

在 Flasgger 中，我正在尝试为接受上传文件的路由创建文档。然而，尽管坚持 the specification，我无法在 Flasgger UI 中显示文件选择器。

我正在使用最新的（截至今天）flasgger==0.9.1 运行 OpenAPI 3 规范（如 "openapi": '3.0.0'）并且我在 Swagger 中看到 this commit-UI，为 POST 文件请求启用文件选择器。

我知道之前有人问过类似的问题，但是 none 其中与 OAS 版本 3 有关。

我的代码片段如下：

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

我在 Flasgger UI 中只得到一个空块输入。 Flasgger 是否可能不支持它，即使 Swagger-UI 支持（我认为它是建立在它之上的）？还是语法错误？

Answer 1

您正在混合使用 OpenAPI 2.0 和 3.0 语法。在 OAS3 中，文件被描述为二进制字符串，即 type: string 而不是 type: file。此外，OAS3 中未使用 consumes、produces 和 schemes 关键字。

尝试以下操作：

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

请注意，OAS3 文件上传需要 Swager UI 3.16.0+，但 Flassger 0.9.1 与 UI 3.14.2 捆绑在一起，似乎无法更新捆绑的 Swagger UI。这种可能性将在下一次更新中添加，Flassger 0.9.2:

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

所以您需要等待 Flassger 0.9.2。

我还建议您使用 Swagger Editor, because syntax errors might cause incorrect parsing/rendering. 说明如何从 Swagger 导出 OpenAPI 文件 UI 以检查生成的 OpenAPI 文件是否存在语法错误，以便您可以在其他地方使用它。