Openapi-specification: Body parameter in v3 has no name

[bugproof]

https://swagger.io/docs/specification/describing-request-body/

Body and form parameters are replaced with requestBody.

In v2 body parameter could have a name. In v3 there's no name at all which is a showstopper for any kind of generation tools and for whoever used the name.

[darrelmiller]

@amd64x An operation can only have one request body and parameter names are scoped to the operation, therefore a code generation tool could choose any constant name e.g. "body", "payload", "content" as the parameter name for the request body in a method. Is there a reason why that wouldn't work for your scenario? Is there an advantage to being able to choose a different name? For most scenarios, the path is a strong indication of what the body contains, providing another place to name it seems redundant.

[bugproof]

@darrelmiller I still think it is useful to have a name like it is in v2. In some cases, a type is not enough to understand what is it for. What if you have just some primitive type like int or string? I don't think naming it "body", "payload" or "content" would mean anything to me. For referenced types, I probably can use a reference id.

[darrelmiller]

@amd64x If it is not clear what the intent of body is from the name of the resource (i.e. the path) then I would recommend improving the path. When you do a GET on the resource, there is no parameter name, so if the path isn't clear, how would you know what you are GETting?

In the two years since this change was made, this is the first time someone has raised this as an issue. I realize it requires thinking about request body a little differently, and that takes a bit of getting used to. However, I have seen so much confusion because people try and treat bodies as "parameters" and they behave very differently in HTTP, so pretending they are like URL parameters is actually harmful.

[bugproof]

@darrelmiller

I have seen so much confusion because people try and treat bodies as "parameters" and they behave very differently in HTTP, so pretending they are like URL parameters is actually harmful.

It's pretty much like how all MVC frameworks work, for example in ASP.NET you have [Body] parameter attribute. In API clients you most probably pass body as a parameter so yes it's pretty confusing to think of it differently.

[tomchristie]

Just signalling that I'm running into this issue too.

Supporting a name to requestBody allows auto-generated or dynamic client libraries to use a more semantically relevant parameter name.

Being able to generate clients that can reference an operation id and a set of semantically meaningful parameter names is hugely valuable, but at the moment any information that's part of the body of the outgoing request has to be referenced obliquely as body=.

[bugproof]

@tomchristie Honestly, I've given up on using swagger(now OpenAPI) to auto-generate client libraries.

It's parseable but you have to define your own schema to parse to. For example, you can't describe generics and so on to generate generic types in strongly-typed languages like C# or Typescript.

The only thing I find useful is to generate types/DTOs because there are many ways to implement communication (many HTTP libraries) and sometimes it's simply faster to write your client manually specifically for your needs including authentication. But for that, you could also use protobuf and define your DTOs there. If you use the same language to write your client and server then it's wise to just share models instead of generating (what I do now and I'm happier)

If you generate your swagger instead of writing it then there's a lot of work to generate it properly to meet all your needs... there's just a lot of time wasted on 1. generating proper swagger to meet all your generation needs 2. a lot of work with parsing it properly and generating it and generally a lot of maintenance to make this work exactly how you want it to work. You waste just too much time you can spend on writing your client code manually and at least it works and looks exactly how you want it to. I spent like 1+ month on making the tooling and still I was not satisfied with the output.

So you have to maintain all the tooling instead of focusing on the code and the product. OpenAPI is not meant for this.

IMO it's only good to generate documentation to refer to when developing your client libraries, or to test stuff, but I prefer insomnia or postman for this. Right now I don't even use OpenAPI because I have no need for documentation. Decide yourself.

What to use instead? Some kind of IDL to generate your models in multiple languages and write your client by hand. For C# developers there's something like typewriter: https://github.com/frhagn/Typewriter to sync your models. Other than that it's not worth the effort

[GHakopian]

+1 on having the name property for auto-generated or dynamic client libraries to use a more semantically relevant parameter name.

[jokedurnez]

+1 !

[iikkamerilainen]

+1, the parameter absolutely should be nameable for auto-generated clients. My path is "document/{id}/reject", POSTing to it rejects the document, but an optional, possibly long rejection comment text is accepted as a body parameter, and now the parameter is called "body" in my auto-generated client after migrating to OpenAPI 3.

[darrelmiller]

@iikkamerilainen Feel free to add x-Name to the RequestBody object and go write PRs to the client generator tooling to use that name. If you have success there, then I'll be happy to consider supporting it being added to the spec. But I'm not going to do the work to add something to the spec that I think is unnecessary and do the work to convince tooling people to implement it.