How do I document a multipart request with apiary?

Question

I want to document a multipart request like the following:

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--

A curl to reproduce this same request would be something like:

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

This doesn't seem to be supported yet. There's an issue here discussing how best to do it https://github.com/apiaryio/api-blueprint/issues/100 — thomax, Sep 13 '16 at 13:41

score 48 · Accepted Answer · answered Jun 13 '14 at 14:25

To create a multipart request with API Blueprint simply create a request with multipart/form-data; boundary=---BOUNDARY Content-type and use the respective boundary markers in the body asset like so:

# 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.

See also this link on Apiary directly https://jsapi.apiary.io/apis/sparkdriveapi/reference/files/upload/upload-file-in-form-data.html But what I see, is that Apiary is not doing very well in that kind of more complex scenarios. The blueprint becomes again just a html style documentation and not a "living documentation" what we want to achieve. Maybe doing all in Postman is better. I still have to investigate how in Postman I can describe nicely all the API parts. — DaveX, Jun 29 '18 at 08:24

How do I document a multipart request with apiary?

1 Answers1

Linked