[Feature Request] Move to OpenAPI / OAS 3.1

[ndreno]

Feature Request

Swagger spec definition is obsolete, most of the code gen tool are now based on OAS 3.x

Describe the desired solution

Transcribe Swagger 2.0 into OAS 3.1

Describe possible alternatives

3.0 may be a good in between, but while moving with breaking changes that would be better to stick with the latest version

Checks

• [x] Have you searched the Firecracker Issues database for similar requests?
• [ ] Have you read all the existing relevant Firecracker documentation?
• [ ] Have you read and understood Firecracker's core tenets?

[kanpov]

Automatically converting from OpenAPI 2.0 to 3.0 via editor.swagger.io takes only a few clicks and seems to produce correct output, so I think the Firecracker team can just do that.

[kanpov]

Here's what it spat out for me, seemingly without reporting any errors: https://gist.github.com/kanpov/45581e5e9b4faeec447a723023a380ab. I can do a PR where I just ctrl+v it

[ndreno]

I would suggest bumping to 3.1

I can review the PR if you want :)

[kanpov]

I would suggest bumping to 3.1

I can review the PR if you want :)

I'm going to make a PR that first does the auto-conversion from 2.0 to 3.0, and then I'll try to do the manual changes needed to migrate from 3.0 to 3.1

[kanpov]

The swagger dir should also be renamed to openapi in my opinion.

[zulinx86]

Hello @ndreno and @kanpov , Thank you for creating this issue and the PR.

Before jumping into it, we'd like to understand your use case well. Could you please share specific problems you are running into with the existing swagger 2.0 file?

In addition, considering the existing customers who create their Firecracker clients based on the current swagger file, we have to start with thinking about the long term plan (e.g., migration period, migration guide, etc.).

Thanks.

[ndreno]

on my side, we use code generators for servers and clients. Most (if not all) are based on OAS3+, that would mean using a different tech/lib to do the same here. We also use a bunch of tool to generate test collections, breaking changes detection, etc.

But my issue was more generic, I mean, OAS4 is announced for the end of the year, it will take a while before it is widely adopted, but Swagger, aka OAS2, is deprecated and code gen, testing tools, etc. are for the best, not maintained anymore, for the worst completely useless as of today (depending on techno of course)

[zulinx86]

@ndreno Thanks for sharing your use case. I understood some code generators that you depend only support OAS3+.

Just of curiosity, could you point me to the reference that OpenAPI Initiative publicly announced "Swagger, aka OAS2, is deprecated"?

In any case, as mentioned earlier, we need to consider existing users depending on the current one, so I think we cannot go forward with deleting it soon like PR #4763 does. We're checking with existing users now, so please wait for a while.

Thank you for your understanding.

[kanpov]

@ndreno Thanks for sharing your use case. I understood some code generators that you depend only support OAS3+.

Just of curiosity, could you point me to the reference that OpenAPI Initiative publicly announced "Swagger, aka OAS2, is deprecated"?

In any case, as mentioned earlier, we need to consider existing users depending on the current one, so I think we cannot go forward with deleting it soon like PR #4763 does. We're checking with existing users now, so please wait for a while.

Thank you for your understanding.

OAS2 is still usable but the OpenAPI specification creators moved onto OAS3.0 6-7 years ago and onto OAS3.1 3 years ago, so it's pretty clear that dropping support for it will come at some point. It's a clear standard (example: autogenerated for .NET Web APIs) and it would only make sense to move the Firecracker API server specification to it.

Any new efforts for specifications are clearly centered around 3.x.

If compatibility is a concern for these customers due to OAS3.1 still being not supported in some tools, I could revert the PR to OAS3.0 instead of OAS3.1.

[zulinx86]

@kanpov Thank you for your input. To be precise, we are not against adopting a newer version :) What we're concerned about is the automation process that our existing users have. I can imagine that they hardcode the path of swagger file and their code generation tool may not support the newer version. So I think we need to keep both for a certain period (I guess we can delete the existing swagger file at bumping the Firecracker major version up to 2.0, since it can be breaking change). That means we also need to have tests ensuring the parity between the existing swagger file and the new OAS 3x file.

Just of curiosity, could you point me to the reference that OpenAPI Initiative publicly announced "Swagger, aka OAS2, is deprecated"?

btw, are you aware of official announcement for deprecation of OAS2?

[kanpov]

@kanpov Thank you for your input. To be precise, we are not against adopting a newer version :) What we're concerned about is the automation process that our existing users have. I can imagine that they hardcode the path of swagger file and their code generation tool may not support the newer version. So I think we need to keep both for a certain period (I guess we can delete the existing swagger file at bumping the Firecracker major version up to 2.0, since it can be breaking change). That means we also need to have tests ensuring the parity between the existing swagger file and the new OAS 3x file.

Just of curiosity, could you point me to the reference that OpenAPI Initiative publicly announced "Swagger, aka OAS2, is deprecated"?

btw, are you aware of official announcement for deprecation of OAS2?

There was no deprecation of OAS2 so the reasons for an upgrade are different, as I've listed. The compatible approach you proposed I do agree with in hindsight, and I'll make a new PR doing it instead once I have the time.