Openapi-specification: [3.0.0-RC2]: RequestBody in PathItem Object

[mission-liao]

It is possible to define a body parameter in Path Item Object in 2.0. Is this behavior deprecated in 3.0 ? ( since we can only define Parameter Object at PathItem.parameters in 3.0, but we don't have a PathItem.requestBody field )

[darrelmiller]

Correct. You will need to define a reusable requestBody in the components section and $ref it to get an similar experience.

[ePaul]

A bit of rationale for not having a requestBody defined on path item level.

Inside a path item, there can be several operation objects for different HTTP methods.

• A GET or DELETE operation would normally not take any request body at all.
• A POST or PUT operation will often have one, but if the same resource allows both PUT and POST, they would have different meanings (POST means often "create subresource of the resource given in the URL", PUT means "create or replace the resource given in the URL"), and thus they would most likely not have the same schema or description.
• A PATCH operation could be similar to PUT, but maybe with less required fields (i.e. JSON merge patch). Or it could be a completely different schema (like JSON patch).

So there is normally no point in defining a shared requestBody for different methods. (As @darrelmiller said, if you have usecases where it happens, you can define it in components and then refer to it from the operations, with just two lines of overhead for each operation.)

[mission-liao]

Thanks for sharing design insight. I'm a tool developer and I'm trying to figure out what's supported in 2.0 (although not a reasonable use case) now might be deprecated in 3.0.