Question

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

如果我尝试通过Swagger定义此API，那么我无法这样做。因为，如果我错了，请纠正我，此操作的参数必须是＆＃39; ＆＃39; 正文和＆＃39; 类型＆＃39;此参数必须是文件。 Swagger要求所有 body 参数必须具有 Schema 对象，并且类型file的所有参数都应该包含＆＃39; ＆＃39;值设置为 formData 。这两个要求都与我们的案例相矛盾。

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

我对API世界相当新，所以我不确定它是哪种情况。

提前致谢。

Answer 1

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

Answer 2

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

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

Answer 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

无法通过Swagger定义我的API;这个糟糕的设计？

3 个答案: