metadevpro / openapi3-ts

TS Model & utils for creating and exposing OpenAPI 3.x contracts.
MIT License
485 stars 64 forks source link

Backward compatibility to OpenAPI v3.0 #84

Closed RobinTail closed 2 years ago

RobinTail commented 2 years ago

This PR might fix the issue #83 by making several types and the builder class generic. The generic types depend on the new type OpenAPIVersion that differentiates 3.0.x and 3.1.x.

Some properties like exclusiveMinimum and exclusiveMaximum become either boolean (3.0.x) or number (3.1.x) depending on the OpenAPI version.

Since the default OpenAPI version is 3.0.0 (though it can be determined automatically from the openapi parameter), these changes might be considered as breaking to the current major version of the library.

I'm open to any suggestions and recommendations on how I could improve this PR to support both 3.0 and 3.1.

Closes #83

RobinTail commented 2 years ago

@pjmolina && @jonluca , please review

pjmolina commented 2 years ago

Thanks for the proposal @RobinTail. Formally, it seems to me pretty correct.

However, I have a concern about the maintainability problems it can introduce in the long term if we decide to follow this path:

In this particular case, the issue was to fix exclusiveMaximum & exclusiveMinimum typing.

The pragmatic alternative (lest cost in terms of maintenance) is: to type both exclusiveMaximum & exclusiveMinimum as number | boolean to support both 3.0.x and 3.1.0. This is what I feel we should do here, so far.

The rationale here is, an Openapi Validator will validate and reports full errors on the document. We can always pass the validator this later, but at building time we are no constraining both approaches. Our goal here is to be able to build the doc (not necessarily to validate). The validator will tell us if valid (needed in any case because it will check for more constraints that the ones enforced by the type-systems).

Thoughts?

RobinTail commented 2 years ago

@pjmolina ,

yes. That make sense. Thank you for sharing. I'll prepare another PR according to the concept you described.

RobinTail commented 2 years ago

Instead of this — #85