How to keep the single resource representation approach using OpenAPI spec

Question

Reading this post (see: 3 How to use a single definition when...) about describing a REST API using OpenAPI (Swagger) specification you can note how to keep a single re

Answer 1

From the Swagger-OpenAPI 2.0 spec, readonly is defined as follows:

Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema. Default value is false.

Since the specification says that a read-only property should not be required, there are no defined semantics for what readonly + required should mean.

(It might have been reasonable to say that readonly + required means it's required in the response, but still excluded from the request. In fact there is an open issue to make this change, and it looks like it's under consideration for OpenAPI 3.0.)

Unfortunately there is no way for a single schema to make properties required in the request, but optional (or disallowed) in the response.

(Again, there's an open issue proposing a "write-only" modifier, possibly under consideration for the next release.)

For now, you would need to create different schemas for these different cases. As described here, you might be able to make these schemas a bit more DRY using allOf composition.