Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Upgrade Guide for v2 #1973

Open
martincostello opened this issue Nov 27, 2024 · 2 comments
Open

Upgrade Guide for v2 #1973

martincostello opened this issue Nov 27, 2024 · 2 comments

Comments

@martincostello
Copy link
Contributor

Howdy folks - after a pointer from @captainsafia, I've just been having a quick look at what would happen if I tried to use Microsoft.OpenApi 2.0.0 in Swashbuckle.AspNetCore using the latest preview.

Support for OpenAPI 3.1 has been a populate ask from our users for quite some time: domaindrivendev/Swashbuckle.AspNetCore#2349.

Unsurprisingly, there's quite a lot of breaking changes to deal with:

Image

Rather than me just blindly chip through those changes until it compiles (let alone tests pass), I figured a migration guide would be a useful starting point. Even if it's just a simple list of changes rather than a full-blown document, as clearly it would be a moving goal-post in the middle of your development, that would go a good way to understanding the effort that would be required for us in more detail.

This looks like it's going to be a non-trivial piece of work to adopt, and will put constraints on us/our users on what functionality will and will not be retained moving forwards compared to v1 and OpenAPI 2.0/3.0.

Things I've found so far:

  • Removal of the JSON reader;
  • Parsing documents is async;
  • Removal of IOpenApiAny;
  • JsonSchemaType replacing string for schema types;
  • OpenApiDocument.ResolveReference() being removed.

Would someone be able to put something together to aid us in preparing to consume version 2? Ideally this is something we (Swashbuckle) can work on in the background so that we could land support for 3.1 relatively soon after you ship 2.0.0 as stable.

@darrelmiller
Copy link
Member

@martincostello There is a blog post that we are trying to finish up that will show all the before and after stuff, and give some explanation as to the why we have made the changes we have. We can certainly make sure it contains all the necessary guidance for migration.

@RachitMalik12
Copy link

@martincostello We also have some release notes here: https://github.com/microsoft/OpenAPI.NET/releases/tag/2.0.0-preview1 that contain details on the breaking changes. Feel free to take a look and see if it helps you get started while we work on the blogpost.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants