[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

• 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.

[bchalios]

We are moving this to parked for now, since there hasn't been movement for a while now. Feel free to ping us when you get time to resume working on it.

[roypat]

Hey all,

we talked about this a bit internally today, and decided on the following path forward for a migration of our swagger file towards OAS 3.1. Generally, we'd be happy to support an updated version of our API documentation in parallel to the existing swagger description, with the swagger description being marked as deprecated, and going to be removed in a major version update. That way, customers also have more opportunity to migrate to generating clients from the new specification on their own time. However, we're also interested in using this migration as an opportunity to figure out ways to automatically keep our specification in sync with what the code actually does. For this we've been briefly looking at solutions for auto-generating OAS 3.1 specifications from the Rust code, for example using https://github.com/juhaku/utoipa. So the next steps here would be

1. Determine if autogeneration of the specification is feasible, and if yes, add autogenerated OAS 3.1 specifications to the repository
2. Maintain both the existing and the OAS 3.1 specifications until the next major version update, with the current swagger specification marked as deprecated.

[ndreno]

Hey there, happy to see that you're taking this seriously ;)

I've been working around OAS for a loonnggg time and to be honest the Code first approach, just, doesn't work.
I would definitely recommend to take this opportunity to move toward Contract first approach. I'm sure you'll find plenty of tools to do a one shot migration from swagger to OAS 3.1 (3.2 is there soon, and be careful 4.0 aka Moonwalk is coming in 2025 as well and has a lot of changes in the format and also in the approach, but be safe it will take 5/10 years to have the whole eco system moving to this one like Swagger to OAS3).

I don't know the Rust eco system, so I'm not sure if the code gen from OAS is good there, but I can have a look if you want :)
openapi-generator is usually a crappy option, they have tons of issue and PRs open...

[roypat]

I've been working around OAS for a loonnggg time and to be honest the Code first approach, just, doesn't work. I would definitely recommend to take this opportunity to move toward Contract first approach.

If contract first works, then I think that's fine too. The main thing we'd like to achieve is to have a single source of truth, instead of having to manually keep code and specification in sync. Whether we go code->spec or spec->code I don't think we have any strong preferences, but...

I don't know the Rust eco system, so I'm not sure if the code gen from OAS is good there, but I can have a look if you want :) openapi-generator is usually a crappy option, they have tons of issue and PRs open...

... this was very much the reason why we suggested code->spec. We've looked at Rust codegen before, and found it to be quite lacking (e.g. the generated code doesn't even compile). And also that our HTTP server implementation is fairly unusual by rust standards (e.g. uses a home grown http framework), so I doubt any off the shelf codegen will work with it :( But if you have any pointers, I'd be more than happy to have a look!