无法通过 Swagger 定义我的 API；这是糟糕的设计吗？答案

【问题标题】：Can't define my API via Swagger; is this bad design?无法通过 Swagger 定义我的 API；这是糟糕的设计吗？
【发布时间】：2015-03-13 05:47:21
【问题描述】：

我们的其中一个 API 接受用户的证书。在当前设计下，用户将原始证书数据转储到有效负载中，并发出内容类型设置为 application/x-pkcs12 的 POST 请求。所以本质上，我们的 API 接受请求正文中文件的原始字节。

如果我尝试通过 Swagger 定义此 API，那么我将无法这样做。因为，如果我错了，请纠正我，这个操作的参数必须是 'in' body 和 'type'此参数必须是 file。 Swagger 要求所有 body 参数都必须具有 Schema 对象，并且文件类型的所有参数都应将 'in' 值设置为 表单数据。这两个要求都与我们的情况相矛盾。

所以我的问题是，这是 Swagger 的限制吗？或者这只是糟糕的 API 设计，我们是否应该以其他方式构建/设计我们的 API？

我对 API 的世界还很陌生，所以我不确定是哪种情况。

提前致谢。

【问题讨论】：

标签： api rest swagger

【解决方案1】：

我相信这仍然可以做到。您的正文参数架构应具有 []byte 类型。当您调用 API 时，您的参数值应该是文件内容的 base-64 编码字符串。这类似于在请求正文中发送二进制 .jpg 文件的内容。

【讨论】：

【解决方案2】：

Swagger 2.0 允许file 类型的参数。这似乎适合您的用例。

parameters:
- name: cert
  in: formData
  description: The certificate
  required: true
  type: file

【讨论】：

【解决方案3】：

OpenAPI 3.0 支持您的方案。之前的版本 OpenAPI/Swagger 2.0 只允许使用 multipart/form-data 请求上传文件，但 3.0 也支持上传原始文件。

paths:
  /cert:
    post:
      requestBody:
        required: true
        content:
          application/x-pkcs12:
            schema:
              type: string
              format: binary
      responses:
        ...

更多信息：File Upload

【讨论】：