OpenAPI 3.1

[achrinza]

This issue is to start a discussion on how to go forward with implementing OpenAPI 3.1 once it hits GA.

OpenAPI 3.1.0-rc0 was "recently" released. It brought about new, breaking changes that may affect LoopBack 4's development.

Most notably (but not limited to):

• Full support for JSON Schema Draft 2019-09 primitive types and Schema Object
• Semver dropped
• OpenAPI 3-specific implementation was dropped in favour of JSON Schema (e.g. exclusiveMinimum and exclusiveMaximum are now numbers)

Potential discussion points:

• This would cause a cascading effect where LoopBack 4 components will have a breaking change.
• What about external tooling (e.g. oas generators)? Should we be able to generate both OAS 3.0 and OAS 3.1 spec?
  • openapi-generator only supports OAS 3.0
  • swagger-ui only supports OAS 3.0

AJV support for JSON Schema Draft 2019-09 is underway:

• JSON Schema 2019-09 and JTD (v8) ajv-validator/ajv#1198

Full Release Changelog:

• https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0-rc0

Suggestion

Update codebase to utilize OpenAPI 3.1.

Use Cases

Some immediate benefits:

• No conversion between OAS3-flavor and original JSON Schema spec
  • Reduced complexity and confusion
• Future-proofing LoopBack 4 for future versions of OpenAPI 3

etc.

Examples

N/A

Acceptance criteria

TBD - will be filled by the team.

[raymondfeng]

@achrinza Great initiative. It's great to see schemas in OpenAPI 3.1 are aligned with JSON Schema. There is one less mapping to be worried about. I guess switching to OpenAPI 3.1 for LB runtime is fairly easy. The challenge is to wait for other libraries to catch up - such as Swagger UI, Swagger parser, AJV, ...

[achrinza]

I'm wondering if we should introduce built-in "converters" so that developers will have the choice to expose either OpnenAPI 3.0, OpenAPI 3.1 or both.

Furthermore, "converters" for OpenAPI decorators (i.e. @get()) and @property({jsonSchema: {}}) would enable developers to gradually convert their codebase to use the latest OpenAPI 3.1 spec.

I'm not sure the feasibility of either converters, but I think it may be worth considering, at least as a long-term goal. That way, any changes to the OpenAPI spec that gets adopted by LoopBack 4 doesn't become a breaking change for the developers.

[yiev]

I think the other libraries did catch up with OpenAPI 3.1/JSON Schema 2020/12 by now. So may it be possible now to support OpenAPI 3.1 in Loopback 4? 😄