Upgrade Guide for v2

[martincostello]

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:

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]

@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]

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

[martincostello]

I've partially upgraded Swashbuckle.AspNetCore to v2 preview 5 here, though a lot of tests are current broken. It isn't yet clear which are mine to fix and which are possible Microsoft.OpenApi v2 bugs - that's something I need to dig into.

I saw there have been two new releases since yesterday when I was looking for migration notes in the release details (which alas only exist for preview 1), so thought upgrading might resolve some of these issues.

However, preview 6 introduced many more breaking changes, and I don't know what the appropriate migration path for them is.

Specifically, the changes in #2106 removed the Reference property from {I}OpenApiSchema which Swashbuckle uses heavily.

@baywet could you or someone on the team provide some additional migration assistance with the path forward here please? The upgrade is proving quite painful/challenging for Swashbuckle.AspNetCore.

[baywet]

Thanks for the nudge here @martincostello. We've already started working on an internal document for the blog post for the announcement of the release which contains a lot of the information you'd be looking for in an upgrade scenario.

I've asked @RachitMalik12 our dear PM to abstract the key information in a markdown document on this repo in a document similar to this one

[martincostello]

Any updates here? I had been using the release notes for the 2.0.0-preview.1 release in GitHub, but it's been removed 😅.

[baywet]

Hi @martincostello
@RachitMalik12 is working on an upgrade guide internally. Thank you for your patience.

As for your comment about releases being removed, are you referring to this one ?

[martincostello]

Yep, sorry my bad, it had flipped over onto page 2, but I thought 1 and 2 had disappeared as it jumped down to 1.6.23 and when I tried to open it by manually tweaking the URL I got a 404 (the latest release has a dot between preview and the number and a v prefix where it didn't before):

[baywet]

yes, we did have issues with CD, tagging etc... and we've had to retag/create the releases in late december/early january. This could have caused some confusion, sorry about that.

[martincostello]

I'm trying to update Swashbuckle.AspNetCore from 2.0.0-preview5 to 2.0.0-preview7 and it's proving incredibly difficult due to the huge breaking changes between the two versions.

Interfaces aren't always useable as they're a read-only model (e.g. Example only has a get) which means needing to use OpenApiSchema or OpenApiSchemaReference, but it isn't clear what to do in the scenario where the interface isn't either of these concrete types. It's also not clear where changes are intentional or are maybe a bug/missing feature.

Even a work-in-progress upgrade guide would be useful to refer to to try and get things working as this is shaping up to be quite a large piece of work to migrate to. I'd prefer to get ahead of the game and help find bugs and give feedback (e.g. #2253) well in advance of 2.0.0 being "done".

[baywet]

Rachit has started a draft PR, but on this repo... which is private https://github.com/MicrosoftDocs/openapi-docs-pr/pull/192 (don't ask me why we need a private repo + a public fork, it's a requirements from our friends in the docs team...)

If that can help, I can share a PDF printout of what we currently have, let me know.

As for the interfaces change, the idea is that consumers like you will use type assertions, in later previews we've also added additional properties that give you the target recursively as well. The main issue we were trying to fix (beyond having a working implementation of references) was to let users know when they might actually be mutating the target when they thought they were mutating a local reference/copy instead.

So a couple of examples:

IOpenApiSchema someSchema = ;// does not matter how you got it

if (someSchema is OpenApiSchemaReference schemaReference)
{
    // it's a reference, just read things
    var schemaType = schemaReference.Type;
    // or update the description/summary for the reference
    schemaReference.Description = "bar";
    // or obtain the target
    IOpenApiSchema target = schemaReference.Target;
    OpenApiSchema definitiveTarget = schemaReference.RecursiveTarget;
}
else if (someSchema is OpenApiSchema concreteSchema)
{
    // it's a schema directly, do whatever you want to it
}

Let me know if you have any additional comments or questions.

[martincostello]

A PDF of the current state would be useful, thanks.

Regarding interfaces vs. types, my main question would be about the else.

What would one do in the case that the interface isn't either of those two implementations but something else?

[baywet]

I'd say throw because something went wrong. We only have two implementations of each of those interfaces. I don't see any reason why we'd have more at this point. Even if the reference needs to be specialized, the specialized type will derive from reference.

The only reason why there might be additional implementations is if the consumer brings additional implementations, again that's possible, but I'm not sure why would anybody do that?

[baywet]

There is the export, some of the reference stuff in there is NOT up to date with the code, which is why we haven't released it yet. Let me know if the formatting is too painful, I'll see what I can do.

upgrade-guide-oai-2.pdf

[martincostello]

Thanks!