Fix request building with formData parameters

[donny741]

Problem

Swaggerization part and request building part of formData parameters behave differently. With this commit formData parameters are being filtered out and only the first one's :schema definition is used inside endpoint description (same as with body parameters). However, in request_factory every single formData param is used to build a payload.
So with parameter definition like this:

parameter name: :name, in: :formData, type: :string

let(:name) { 'Name' }

An empty requestBody definition for that API action is generated (because there is no :schema key)

With this variation:

parameter name: :form_data, in: :formData, schema: { type: :object, properties: { name: { type: :string } } }

let(:form_data) { { name: :name } }
let(:name) { 'Name'}

the correct swagger definition is generated, but the controller receives the name parameter that is nested inside the form_data object. And this does not match the defined schema.

Solution

This can be fixed by either changing request_factory so it puts first formData parameter inside request body (implemented in this PR), or changing swagger_formatter so that it builds schema definition from multiple formData parameters. Don't know the reason why swagger_formatter was initially implemented this way, so I went with the first option.

[sergioisidoro]

That .first worries me. Doesn't this just work with the 1st form parameter?

{ name: 'f1', in: :formData, type: :string },
{ name: 'f2', in: :formData, type: :string }

Wouldn't f2 be excluded?

The test seemed to test for 2 parameters in FormData, but now it only tests one. Could you return the test to have 2 form parameters to make sure it works with more that 1 form parameter?

[donny741]

@sergioisidoro Thanks for your feedback! Yes, that's exactly how it would work. I have explained the reasoning in the "solution" paragraph. body parameters work the same way.
Another solution would be to make swagger_formatter accept multiple parameters because now it accepts only the first one and logic in these places diverge.

I agree this solution isn't great and is more of a quick fix. Currently, to work around this issue we define the first formData param just for SwaggerFormatter and then redefine the same schema in separate params to make RequestFactory work.

[sergioisidoro]

Ok, let me take a bit longer to look into this, and see if I can figure out the historical background behind the body param. My guess is that it is also not supposed to be like that 🤔

[mlh758]

I don't think the current implementation is actually working for people. #348 is a long thread of people resigned to either having the integration test work, or their generated documentation being correct. I was about to submit pretty much this same PR but happy to see it's already been done.

I also think that conceptually it makes sense to only have a single body parameter supported since you can only send one body.

[braindeaf]

I have come up against this issue recently. And I am very keen to solve it, happy to work on it if we get more ideas on the best solution.

[kennon]

+1 :-)

[abstracts33d]

+1 :-)

[nparker-tc]

I have run into this issue recently and the workaround here: #348 (comment) worked for me.

 parameter name: :'', in: :formData, schema: {
  type: :object,
  properties: {
    client_id: { type: :string },
    client_secret: { type: :string },
    grant_type: { example: 'client_credentials', type: :string },
  },
  required: [ 'client_id', 'client_secret', 'grant_type' ]
}

response '200', 'Token created' do
  example 'application/json', :succesful_token_example, {
    'access_token': 'FeXebuMLItU3UPpcXlUgGkxeXoWLgX9CULUQ6FBAFjs',
    'token_type': 'Bearer',
    'expires_in': 7200,
    'scope': 'public',
    'created_at': 1677685057
  }
  let(:'') { { client_id: 'client_id', client_secret: 'client_secret', grant_type: 'client_credentials' } }
  run_test!
end

[mlh758]

I never thought I'd say this... but I think I prefer the monkey patch 😞

[braindeaf]

Which solution was the monkey patch?

[Drowze]

Just faced this issue today - I don't think there's currently a good way to document formData parameters using OAS 3.0 🤔

Looking forward to this change :)

[MichaelAlexanderBanuelos]

any update on this?