search

metadevpro / openapi3-ts

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

Targeting certain OpenAPI versions #90

Closed okybr closed 1 year ago

okybr commented 2 years ago

As you know, the JSON schema for OpenAPI versions 3.0.x and 3.1.x differ. Currently, this package uses the same model for both versions. Thus, it cannot guarantee that the produced openapi.json will comply either version. In particular, it's not possible to specify the targeted OpenAPI version which is desirable as tools, that have the openapi.json as input, might only support certain versions of OpenAPI.

pjmolina commented 2 years ago

Thanks for pointing it out @okybr ! Thinking aloud if splitting the library in two to produce a 3.0 version and a 3.1 will help the uses cases that most people use. Opinions? @RobinTail @okybr

pjmolina commented 1 year ago

Hi! Moved to action with the new year. As commented by some of you: breaking changes in OAS 3.0 to OAS 3.1 makes it impossible to serve both versions at the same time properly.

So, I decided to:

  1. Fork a new library supporting only OAS 3.1.x in openapi31-ts repo, npmjs v. 1.0.0
  2. Evolve this one to support only OAS 3.0.x here openapi3-ts this repo, this package at npmjs v. 4.0-next (to be done)
  3. The best effort approach will be frozen here in version v. 3.1.2. Could be patched for security updates and so on if needed.

As an alternative, we can create a new fork called: https://github.com/metadevpro/openapi30-ts to be more explicit in the forking and preserve what we have here.

What do you think/prefer? Strict OpenAPI 3.0.0 here or in a different repo (3rd repo)?

okybr commented 1 year ago

What do you think/prefer? Strict OpenAPI 3.0.0 here or in a different repo (3rd repo)?

In my opinion, "3" should mean "latest 3.x", "30" should mean "latest 3.0.x", and "31" should mean "latest 3.1.x".

Also, let's hope that OpenAPI won't ever reach version 30.

I decided to: Fork a new library

I don't think that this is a nice way to support both OpenAPI versions. I'd prefer to have a single repository with a single package to support both versions. Although they are different, they still share much. You could simply have OpenAPI_3_0.ts and OpenAPI_3_1.ts files that share code through another file, or so.

Also, the openapi31-ts repository does not include the Git history from the original repository. This is very unfortunate because you can't use Git features like git-blame and you can't easily comprehend what changed in the code since the fork with git-diff.

Still, thank you very much for your efforts and the nice work!

pjmolina commented 1 year ago

After your comments @okybr I tried to give it another loop and separate the version in the same repo (this one). The PR #92 is an attempt for it (obviously with a breaking compatibility).

What do you think?

pjmolina commented 1 year ago

Merged. Publishing as v. 4.0 with breaking changes.