如何使用 apiary 记录多部分请求？

Posted 2023-03-30

【中文标题】如何使用 apiary 记录多部分请求？

【英文标题】：How do I document a multipart request with apiary?

【发布时间】：2014-06-13 14:16:47

【问题描述】：

我想记录一个多部分请求，如下所示：

Content-Length: 477
Content-Type: multipart/form-data; boundary=---BOUNDARY

-----BOUNDARY
Content-Disposition: form-data; name="image[file]"; filename="image.jpg"
Content-Type: image/jpeg
Content-Transfer-Encoding: base64

/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z
-----BOUNDARY--

一个curl 来重现这个相同的请求是这样的：

curl -F "image[file]=@file.jpg" http://localhost/images

【问题讨论】：

这似乎还不被支持。这里有一个问题，讨论如何最好地做到这一点github.com/apiaryio/api-blueprint/issues/100

【参考方案1】：

要使用 API 蓝图创建一个多部分请求，只需使用 multipart/form-data; boundary=---BOUNDARY Content-type 创建一个请求，并在正文资产中使用相应的边界标记，如下所示：

# POST /images

+ Request (multipart/form-data; boundary=---BOUNDARY)

        -----BOUNDARY
        Content-Disposition: form-data; name="image[file]"; filename="image.jpg"
        Content-Type: image/jpeg
        Content-Transfer-Encoding: base64

        /9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a
        HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIy
        MjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIA
        AhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEB
        AAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AL+AD//Z
        -----BOUNDARY

+ Response 201 (text/plain)

        Ok.

【讨论】：

在 Apiary 上直接查看此链接jsapi.apiary.io/apis/sparkdriveapi/reference/files/upload/… 但我看到的是，Apiary 在那种更复杂的场景中表现不佳。蓝图再次变成了一个 html 样式的文档，而不是我们想要实现的“动态文档”。也许在 Postman 中做所有事情会更好。我仍然需要研究如何在 Postman 中很好地描述所有 API 部分。