Giters

metadevpro / openapi3-ts

TS Model & utils for creating and exposing OpenAPI 3.x contracts.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Targeting certain OpenAPI versions

okybr opened this issue · comments

commented

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.

commented

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

commented

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)?

commented

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!

commented

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?

commented

Merged. Publishing as v. 4.0 with breaking changes.