Documentation on usage with file uploads

[rusterholz]

I've been having a truly ludicrous amount of difficulty getting this gem to work when one of the required parameters is a file upload. I'm probably doing something wrong somewhere, and I'd love to check my approach against the documentation, but I can't find any mention of file uploads in the documentation for this project.

Could someone who knows how to use this with a file upload please, please, PLEASE add that information to the Readme, and add an example of it to the example folder?

[oestrich]

Are you uploading with the Content-Type of multipart/form-data? If Content-Type is set to that it will strip the contents of the parameter for documentation and leave it as [upload data]. See here and below here.

[rusterholz]

Thanks for the tip, and the speed of your response. I suspect that's probably the cause, it makes sense that Rails probably wouldn't parse it correctly if the header were wrong. I won't have time to get back to that part of our code for a few days, but I'll definitely make that change.

To me, the main issue here isn't that file uploading isn't (or wasn't) working for me; the main issue is that there doesn't appear to be any mention in the documentation about what people should normally need to check in order to upload files with this gem. (I'm not averse to reading the code, but it's not something I normally expect to have to do to accomplish something that seems like a fairly typical usage.) I realize that this particular behavior is really the expected behavior of Rails with that header, and not the fault of anyone contributing to this gem, but... if some mention of this gotcha could just be documented in the Readme (or, better yet, an example of working file uploading added to /examples) it might save somebody else the two-hour headache that I had, and that's what I'm really hoping for.

[amedrz]

@rusterholz could you post what your solution was? I hit the wall on this too. Thanks!

[oestrich]

Closing this as I think we've got it in place. I've added an example of uploading to the example app. https://github.com/zipmark/rspec_api_documentation/blob/master/example/spec/acceptance/uploads_spec.rb

[sbwoodside]

@oestrich why don't you include

  header 'Content-Type', 'multipart/form-data'
  parameter :file, "File", "Type" => "Multipart/Form-data"

In the example?

[oestrich]

I mostly included it as an example how to get something uploading in general, not as something that would generate appropriate documentation. I'll gladly accept a PR if you want to expand upon that example.

[sbwoodside]

OK. I'm currently trying to figure figure if my controller is correct for accepting files with multipart/form-data so as to be efficient for large files, and then how to test that correctly. So far I have:

Before section:

resource "ObjectStoreObjects" do
  before(:each) do
    @user = FactoryGirl.create(:user)
    login_as(@user, :scope => :user)
    @object_store_object = FactoryGirl.create(:object_store_object, :user_id => @user.id, :name => 'og.png', :content_type => 'image/png')
  end

Test version 1:

post '/object_store_objects' do
  parameter :file, 'POST the file to the server'
  let(:file) { Rack::Test::UploadedFile.new('spec/fixtures/aldus_aldon.png', 'image/png') }
  response_field :id, 'The new object ID'
  example_request 'Create a new object' do
    expect(status).to eq(201)
    object_store_object_response = JSON.parse(response_body)
    expect(object_store_object_response['user']['id']). to eq(@user.id)
    expect(object_store_object_response['content_type']). to eq('image/png')
    expect(object_store_object_response['name']). to eq('aldus_aldon.png')
  end
end

Test version 2:

post '/object_store_objects' do
  let(:file) { Rack::Test::UploadedFile.new('spec/fixtures/aldus_aldon.png', 'image/png') }
  header 'Accept', '*/*'
  header 'Content-Type', 'multipart/form-data'
  parameter :file, "Attachment", "Type" => "Multipart/Form-data"
  example "add an attachment" do
    do_request( file: file )
    expect(response_status).to eq(201)
  end
end

Does version 2 have the required syntax to make rspec_api_documentation do a multipart form upload?

[sbwoodside]

Update: the controller is verified using curl -F "file=@spec/fixtures/foo.png;type=image/png" -u foo:bar "http://localhost:3000/object_store_objects"

So my question is just: in order to test multipart form uploads, do I need to include the following in my test?

header 'Accept', '*/*'
header 'Content-Type', 'multipart/form-data'
parameter :file, "Attachment", "Type" => "Multipart/Form-data"

[oestrich]

If you're just interested in testing, then what is in the example app is enough to get you by. The biggest thing is just using a Rack::Test::UploadedFile

[colszowka]

For some reason this isn't working for me - I set it up as described in the example, but what I actually see in the params is the inspect string variant of the rack test file I pass.

I got over the issue for the time being by wrapping the file param accessor in a controller method and stubbing it in the test with the file instance I pass, but I'd really prefer to avoid this if possible.

[mattcameron]

Posting in case it can help anyone else having issues, as it took me hours to figure out.

I struggled uploading a file along with other form data, despite using Rack::Test::UploadedFile.

As per @colszowka, when viewing the params I would get a hash as follows (for the file param):
{"original_filename"=>"image.png", "tempfile"=>"#<File:0x0000557b98315588>", "content_type"=>"image/png"}

or if setting the 'Content-Type' header to 'multipart/form-data'
{\"original_filename\":\"image.png\",\"tempfile\":\"#\\u003cFile:0x000055aee6479bf0\\u003e\",\"content_type\":\"image/png\"}

Frustratingly, the code worked with a regular rspec request test, and when using Postman.

Eventually when pouring through the source code I realised that the params are being formatted depending on the configuration set for request_body_formatter.

In my case it was set to :json which meant it was calling .to_json on the params which would render the uploaded file as a hash instead of a file.

The rest of my API uses json, so that was a sane default. To overcome this, I used raw_post to set the params with the file, and avoid the request body formatting.

Old:

let(:data) do
  {
    data: {
      foo: 'bar',
      file: Rack::Test::UploadedFile.new("path/to/image.png", "image/png")
    }
  }
end

example 'uploads form data' do
  do_request(data)
  expect(response_status).to eq(200)
end

Updated:

let(:raw_post) do
  {
    data: {
      foo: 'bar',
      file: Rack::Test::UploadedFile.new("path/to/image.png", "image/png")
    }
  }
end

example 'uploads form data' do
  do_request
  expect(response_status).to eq(200)
end

This now also seems to work regardless of whether I set header 'Content-Type', 'multipart/form-data' or not.

Hope this helps someone else!