Support description option body_param

[dgutov]

This is a proposal to fix #42. See the included commit message for details.

With this change, we can at least have textarea input for complex types that couldn't be represented with form fields.

The included parameter names and descriptions are lost. We could try to put them in some formatted way into notes, but since there's no guarantee that it supports markdown, the result would be messy.

Ideally, this should be eventually solved in #39.

[Nerian]

@tim-vandecasteele Is there any reason not to merge this?

[dblock]

Sorry this took so long. A few people are taking over the project and things are going to move forward now.

I am not convinced this is a good idea. If you're posting a multipart form, you got params, if you're posting and parsing JSON, you still have params. Doesn't look HTTP to me to have a free-formed body otherwise.

What do you think?

[dgutov]

Doesn't look HTTP to me to have a free-formed body otherwise.

Guess so. Since Grape unifies both query and body parameters as far as the user code is concerned, this shouldn't be necessary.

But we've been using this as a escape hatch to be able to use Swagger UI for requests that are not supported by grape-swagger, such as any parameter with array value, or a nested structure, etc (#39).

Not sure if all these can be supported with Swagger. If so, that would be a better alternative. Otherwise, I think it's more important to allow performing all kinds of requests that Grape supports, rather than allow only those we can support it a "nice" way.

[dblock]

I am looking for some (strong) opinions of what to do with this PR :)

[krisalyssa]

If I'm reading https://github.com/tim-vandecasteele/grape-swagger/issues/42#issuecomment-20442937 correctly, this is something that Swagger supports, so we should probably support it as well. Whether or not this PR is the way to support it remains to be discussed.

I've read through the file changes, and I can't quite get my head wrapped around the use case. Can someone (@dgutov?) elaborate more?

[dgutov]

@CraigCottingham

Can someone (@dgutov?) elaborate more?

Could you ask a specific question?

[krisalyssa]

Could you ask a specific question?

1. What's the use case? How would this feature be used?
2. Does this feature allow one to do something that otherwise isn't possible, or does it simplify what would be an otherwise complicated workaround?

[dspaeth-faber]

In #101 is a screen-shot show how swagger can document a body which should be a json string.
You can see and test it here best.

The good thing is, when you use an entity. You can got to Model Schema and prefill the body with a valid json structure.

For post, put, patch this works allready, because param_type is automatically set
to 'body' (Edit: when you use a type which says false on is_primitive?).

In my point of view the only thing needed to do is enhance the documantation and maybe add in grape a dsl like body ensteed of requires or optional.

[dblock]

@dspaeth-faber I would be interested in a body parameter for Grape.

[dspaeth-faber]

@dblock Like I did figure out today this is a little bit more complex. When you start with the body parameter you also have to change the resulting params hash. Today a post of json data will not directly be query able from the params hash. You have to query every key seperatly. As an example:

The post data:

{
   "id": 1,
   "some_data": {
      "ddd" : 1
   } 
}

When you want to get the hole body as one hash in your endpoint you have to recreate it:

 body= { id: params['id'], some_data: params['some_data'] }
 # but I would like to get
 body=params['body']

I did walk around this for my self be wrapping the params hash into my Entity
and reserialize it. Maybe grape should wrap all params into a Presenter/Entity.

But this make's the body parameter more complex.

[dblock]

The body POSTed is parsed by a parser. The raw value goes into env['api.request.input']. You could probably alias that as body on the request object, but that should not be a params['body'], that's not a parameter per-se, especially that it can be parsed into all kinds of parameters.

The default JSON parser parses JSON content-type into params. Grape/Rack also supports form multipart content.

[dgutov]

@dblock

I would be interested in a body parameter for Grape.

Does it make sense for Grape?

How would it work differently from required or optional? Would it just prohibit assigning that parameter from query? Doesn't sound very useful to me.

I think the body-ness works better as additional metadata, for example like implemented in this pull request.

@CraigCottingham Sorry for being brief:

1. I think that has been explained well enough in this and related issues.
2. The former (allow one to do something that otherwise isn't possible). Although it might be better to implement those features in a different way, in the long run.

[dspaeth-faber]

@dgutov In my point of view it makes a lot of sence. The documentation hash is noise. When I try to understand api code I will in the first place skip the documentation hash but read the statements. For instance route_param is a clear statement. When I read it I know instantly this parameter will be placed in the url.

When I do some thing wrong with this statement I will get feedback instantly. But the documantion Hash gives no feedback. Some day some one will complain the documentation is wrong that's all.

Furthor validation that they only can be placed where they are defined (query, form, body) would be good thing too.

[albertogg]

Can we revive this discussion? Does anyone has put a thought into this?

[dspaeth-faber]

👍 but no, I have not put any thought into this

[u2]

What now?

[qd3v]

Am I right, we can't use something like this still? I mean sending json data.

So we limited with curl -X POST --header 'Content-Type: application/x-www-form-urlencoded'?
BTW, I even tried this:

But content type header overwritten at the end with urlencoded one:
curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' --header 'XAuthToken: 123' -d 'name=123&venue=123' 'http://localhost:3000/api/v1/events.json'

[LeFnord]

please re-target against swagger-1.2 branch or close

[dgutov]

Actually, I'm not sure this approach should be preferred anymore.

From trying out the swagger-1.2 branch, it seems like it does try to determine whether it can represent the call's parameters via forms, and if not, adds a body parameter.

That doesn't always work, though. For instance, it adds a body parameter for requires :words, type: Array, but if I specify the array's elements as hashes:

      requires :words, type: Array do
        requires :letter1, type: String
        requires :letter2, type: String
      end

then the resulting interface shows an obviously broken form with two fields (words[][letter1] and words[][letter2]), and no body parameter input area.

Anyway, it seems like fixing the edge cases like this can be a better way forward.