blob 的 Swagger 规范表示

Question

我正在为一个新端点创建一个 swagger 规范，该端点将接收作为二进制数据的文件。您如何在 swagger 规范中表示这一点？我将对象视为一种数据类型，但这似乎不是我正在寻找的。过去有人这样做过吗？

据我所知，这个问题不是重复的，因为它专门涉及二进制或“blob”对象类型。

Answer 1

由于 swagger 描述了 RESTful Web 服务，因此任何二进制数据都将进行 Base-64 编码，将其转换为字符串。因此，指定它的方法就是将其定义为字符串。

Answer 2

TL;DR，在架构中设置属性 "format": "binary"。

然后，如果您使用理解此属性的生成器，则返回的对象将被键入为 blob。

blob 包含 mime 类型和二进制数据。二进制数据看起来像字符串，因此最接近的合适 json 模式标量类型是“字符串”。但是，除非您的服务器显式返回 Base 64 编码文件，否则您的端点可以返回任何 mime 类型的任何二进制数据。例如，如果您的端点返回 pdf 文件，您可以按如下方式描述响应：

        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                },
                "examples": {}
              }
            }
          },