Request body properties can't be defined

I’m not sure this is something that the OpenAPI mandates to be implemented the way it is now, but currently there is no way to define a set of properties for a Request body, it’s only possible to select a single data type - either a basic one (int, string) or one of the data types defined by the user.

Also, one can’t define multiple request bodies with the same media type (e.g. application/json).

I have an example at hand right now: a user data type that has firstname, lastname, email, enabled, admin and other properties as part of the data type, but not password. The PATCH method could be used to change any of the properties if the user is admin, and only firstname, lastname and email if the user is a regular user. This method could also be used to change the password, but in this case either a prt (password reset token) should be provided or the current password and a new password (password_new) if the user is changing his own password. Or, if the user is admin and changing other user’s password, just password_new is enough.

Today I have to either create multiple user data types for all this combinations or to embed all the possible fields with the explanation of each combination and condition to a single user data type, or (as I do it now) to specify everything in the description of the method and provide the possible combinations in the examples of the single request body media type ‘application/json’.

I believe it would be better to be able to define multiple request body variants with the same media type and custom properties sets, maybe with a Name and a Description for each one (basically, for the request bodies to be definable the same way the user data types are).

[GimpMaster]

Thank you Eric! FYI ApiCurio is awesome. We are using it in our workflows for creating docs, then downloading the yaml and importing into postman for validation testing. It’s a great tool, much better than hand writing yaml.

[EricWittmann]

As for @anatoli26’s issue of multiple request bodies - I think you’ve run up against a bit of a limitation in OpenAPI itself. You cannot create multiple request bodies using the same media type.

BUT…considering this problem more, I think that perhaps the oneOf feature of JSON schema would allow something like this. In your case it might look something like:

post:
    summary: Operation Summary
    description: Operation description.
    operationId: myPostOperation
    requestBody:
        content:
            application/json:
                schema:
                    oneOf: [
                        { "$ref" : "#/components/schemas/UpdateUser'},
                        { "$ref" : "#/components/schemas/UpdateUserAdmin'},
                        { "$ref" : "#/components/schemas/ChangePassword'},
                        { "$ref" : "#/components/schemas/ChangePasswordPRT'},
                        { "$ref" : "#/components/schemas/ChangePasswordAdmin'}
                    ]

You could configure the title and description of each of those referenced schema types. I’m honestly not sure how something like ReDoc would render that, but OpenAPI at least allows it. Of course you could inline all those schemas rather than $ref them, but I would think referencing them would be a better practice.

Sadly Apicurio does not yet support oneOf, but it’s something we could try to prioritize if the community valued it.