[REQ] OAS 3.0 support of readOnly/writeOnly modeling

[jimschubert]

Is your feature request related to a problem? Please describe.

Yes, missing support for OAS 3.0 feature of readOnly and writeOnly properties within a model.

Discussion came up on Slack, and I'm documenting it here since we need to implement this for full OAS 3.0 support.

Describe the solution you'd like

Provide a writeOnlyVars to match other vars in our codegen model. Support differentiation between request models and response models.

Describe alternatives you've considered

Early discussions about writeOnly on OAI suggest domain modeling around usage of allOf. See OAI/OpenAPI-Specification/issues/425.

Additional context

OAS 3.x Schema Object supports two properties, readOnly and writeOnly. These properties are defined as:

Field Name	Type	Description
readOnly	boolean	Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.
writeOnly	boolean	Relevant only for Schema "properties" definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.

We should validate that a property is not both readOnly=true and writeOnly=true. This validation should be excluded from strict spec skipping as having a property both readOnly and writeOnly should be a logical error with undefined behavior.

The use of SHOULD NOT in the spec is defined via rfc2119:

SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.

So, we're not technically out of compliance with the spec in relation to readOnly and writeOnly since our use case to support OpenAPI 2.0 and OpenAPI 3.0 functionality in the same generator + template combinations could be considered a "particular circumstance". However, the we are out of compliance with the clause regarding required because this makes the property required only in a request or response structure, and not both.

My proposal is to do multiple passes on models defined in the OpenAPI result object and sort these into an array of "RequestModels" and an array of "ResponseModels", leaving our current "models" collection as a raw collection for backward compatibility. This would allow us to have the same schema definition defined appropriately (according to the specification), without hacky workarounds like adding arbitrary prefixes or suffixes to differentiate.

We may be tempted to suggest that users split their schemas, similar to the recommendation linked above (OAI/OpenAPI-Specification/issues/425), but this will only address the issue for those users who own/manage their specifications. To allow code generation from external systems which follow OpenAPI 3.0 specification, we'd need to support this use case.