Why does #/bodyParameter require a "name"?

[themihai]

I'm wondering why bodyParameter schema requires a "name". Makes sense only if the parameter is sent/set in query or perhaps path but doesn't make sense if the parameter in value is body isn't it? Unlike the query string parameters json/xml objects don't have a name.

"bodyParameter": { "type": "object", "required": [ "name", "in", "schema" ],

[webron]

It's for documentation purposes. In previous versions, it had to be 'body'. In 2.0, it can be pretty much anything that you may find descriptive to the body itself.

[themihai]

Wouldn't it make sense to use a different term(e.g. label although there is a "description" field which pretty much solves the documentation issue) ? Isn't name used to name the parameters of simpleType How do you document a parameter which is of simpleType? (i.e a string)

[webron]

I don't follow your last question.

[fehguy]

here's a practical usage of why you need to have names on parameters:

https://github.com/swagger-api/swagger-js#need-to-send-an-object-to-your-api-via-post-or-put

var pet = {
  id: 100,
  name: "dog"};

swagger.apis.pet.addPet({body: pet});

This is doable because the input parameter has a name attached to it. And of course, the operation can have query params, header params, path params, etc.

[themihai]

@webron See the example below. It seems to me that in this case "name" is actually the name of the parameter and is no longer documentation. If the "name" would serve as documentation only it shouldn't be required (just like description) isn't it? My concern is that serving a double purpose adds confusion and complexity to the schema even if it doesn't need (there is a "description" field, right?).
@fehguy isn't possible to achieve the same result using the description field?

"parameters":[{"name":"username","in":"path","description":"The name that needs to be fetched. Use user1 for testing. ","required":true,"type":"string"}],

[webron]

@fehguy just gave you an actual use case example as to why it is needed. There's no real double purpose here.

Also, the schema is not the issue, it reflects the spec itself, which requires it.

[themihai]

@webron the issue is about the specifications. Let me know if there is any other place where it should be discussed.
When in is query the name field of the schema represents the query field when in is body it serves as documentation so this sounds like a double purpose.
What I propose is to use an existing field (e.g. description) or a totally new (preferred) field (e.g. label, alias or whatever the spec developer chooses) and make the "name" optional.

Another reason is that in practice is optional because the client doesn't send it to the server if the request is JSON so I think it doesn't make sense to be required by the schema.

@fehguy I assume that's an example from the current javascript client implementation but I doubt it can't be done using a new field name/keyword which could be conflict free.

[fehguy]

Then fair enough, it is technically possible to not have a name param for a POST where it's not an mulitipart/form-data or www-url-encoded type.

[webron]

It could be implicit, but it would be generated by display tools. Look at swagger-ui, that provides you with the name as an identifier for the field. It would still end up calling it body or payload.

[themihai]

I think the labels ( Parameter and Value) displayed on swagger-ui totally make sense for form encoded requests but for JSON requests they are confusing . A parameter implies that it has a value but the JSON requests require raw json only without parameter/value identifiers.
I think the UI should read just "Raw JSON" with no Parameter/Value columns or/and perhaps provide an editor(optionally) like google (though I'm not really a fan of it).
[0] https://developers.google.com/apis-explorer/#p/groupssettings/v1/groupsSettings.groups.patch

[zanona]

I have to agree with @themihai on this for application/json body types. By requiring a name to the body parameter, it gives me the impression that the body content would be wrapped on a given-name object and that the request would also allow multiple body params.

[webron]

@zanona The idea behind the body parameter name is to possibly give an extra meaning to the parameter, but it doesn't change it. Nowhere in the spec does it say that it wraps anything, and the spec is explicit that there can only be one body parameter.

[webron]

Meta issue: #565