Docs generation fails if a file is uploaded as part of a spec

[oestrich]

HtmlWriter can't handle the encoding:

lib/rspec_api_documentation/html_writer.rb:25:in `write': "\x89" from ASCII-8BIT to UTF-8 (Encoding::UndefinedConversionError)

[pollingj]

I've just hit this issue. Is there a fix for it?

[oestrich]

Not yet. I'm not entirely sure how we'd fix the problem. Do we snip out the upload data or leave it in bloating the docs? If we take it out then we're not really documenting the whole example response.

I thought it might be cool to detect the upload and save it out along side the docs so we can replace it with a link so people can download it.

[pollingj]

I was thinking it could detect the upload data, and just replace it with a string saying something like "upload data"?

[rogercampos]

Also hit this, a fix would be very appreciated

[jejacks0n]

I have not yet experienced this, but I will shortly.. I was here to create a different issue, but yeah, I agree with @pollingj -- replacing it with something that indicates it was a file is fine by me.

[cutalion]

Is it possible to manually add a section to docs meanwhile?

[oestrich]

Sure, depends on how you're hosting them though. If you're using the HTML writer just add a new link in the index page and corresponding HTML page. The JSON writer is similar, but make sure you format the example correctly so Raddocs (or similar) can view it.

I'll look into this a little bit more and see what I can come up with.

[jejacks0n]

Keep in mind that the path is removed before rebuilding, so you would have to do this manually every time you generate the docs.

[jejacks0n]

I did something similar by adding a controller tests outside of the acceptance specs (for a real spec for it), and did the request/response in such a way in the acceptance specs that makes it appear as though there was a file attached in the request.

eg. let(:attachment) { '[File Attachment'] }, then find and update the record with an attachment manually (only works on update). It at least simulates it in the documentation.

[oestrich]

I think I have a working solution for this. Could everyone check out this branch and see if it works for them?

https://github.com/zipmark/rspec_api_documentation/tree/uploaded_data

[pvertenten]

Doesn't seem to support files in nested documents.

[Ruxton]

@oestrich I just put a PR in to expand upon your solution that wasn't working for a few people.

[dalizard]

@oestrich I am having exactly the same problem with an uploaded file. I was thinking about opening a PR, but saw this thread. What is the current state of the issue?

P.S. The uploaded_data branch does not work for me. I had to update the File.open mode in order to avoid encoding problems. See here dalizard/rspec_api_documentation@94243ef

[oestrich]

@dalizard Can you try out the branch again? Merged in @Ruxton's changes.

[dalizard]

@oestrich It works! Any idea as to when this could be pushed to master and released?

[Ruxton]

FWIW we've been using this as part of our CI process in 3 separate projects since I sent this PR and are yet to come across any issues

[oestrich]

Awesome, I'll merge it in later today then and push a new release.