[DRAFT] 2.0 upgrade guide working doc

[Rachit Malik (RachitMalik12)]

No description provided.

[Rachit Malik (RachitMalik12)]

Martin Costello (@martincostello) Hi Martin! Please refer to this as a work in progress, upgrade guide. We will work on this in the open and keeping adding to it as we have more preview bits added. Please let us know if you have any feedback or questions or if we are missing anything you'd like more info on.
cc: Safia Abdalla (@captainsafia)Vincent Biret (@baywet)

[Martin Costello (martincostello)]

Rachit Malik (@RachitMalik12) Thanks for providing this. I've made various suggested edits to the current content.

My main feedback so far based on my (still ongoing) move in Swashbuckle would be to have a dedicated section showing how the reference handling has changed with the type checks. For example the need to do things like:

publicvoidProcessSchema(IOpenApiSchemaschema){if(schemaisOpenApiSchemaconcrete){// Do something}elseif(schemeisOpenApiSchemaReferencereference){// Do something else}}

I'll be sure to leave any additional feedback that might be useful once I've gotten Swashbuckle working with the preview7 (as that's what ASP.NET Core 10 preview 2 is compiled against).

[Martin Costello (martincostello)]

I've also been tripped up by IOpenApiSchema.Type now being a [Flags] enum and had to fix a few things like this:

- if (schema.Type == JsonSchemaTypes.Array)+ if (schema.Type is { } type && type.HasFlag(JsonSchemaTypes.Array))

People might miss this and introduce subtle bugs if they just one-to-one map the strings to the values like:

- if (schema.Type == "array")+ if (schema.Type == JsonSchemaTypes.Array)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Rachit Malik (RachitMalik12)]

Hey Martin Costello (@martincostello),
Thanks for the feedback! We have decided to merge this PR and open a new one with a new set of changes so we can keep this guide moving and ensure it is sync'ed with code changes including the one you've listed below and the Flags enum.
We would also be happy to receive any contributions regarding the requested additions to the doc - if you have the time of course :) - no worries if not, the team is doing their best to keep this moving along given the resources we have - I know it has been slow, apologies for the delays.

Also, one concern I have is that the version you are using (preview7) is a few months old and we've made some more updates since then, Safia Abdalla (@captainsafia) what is the roadmap for moving ASP.NET to a more later preview? I just worry if some of the issues you encounter during your upgrade are fixed in the later previews, so you don't need to spend the extra time in fixing it.
cc: Vincent Biret (@baywet)

Rachit Malik (@RachitMalik12) Thanks for providing this. I've made various suggested edits to the current content.

My main feedback so far based on my (still ongoing) move in Swashbuckle would be to have a dedicated section showing how the reference handling has changed with the type checks. For example the need to do things like:

publicvoidProcessSchema(IOpenApiSchemaschema){if(schemaisOpenApiSchemaconcrete){// Do something}elseif(schemeisOpenApiSchemaReferencereference){// Do something else}}

I'll be sure to leave any additional feedback that might be useful once I've gotten Swashbuckle working with the preview7 (as that's what ASP.NET Core 10 preview 2 is compiled against).

[Martin Costello (martincostello)]

ASP.NET Core 10 Preview 3 shipped yesterday, so I'm now up to preview.11. Due to breaking changes in subsequent previews there are constraints on how far forwards I can jump in my own code before I hit a "compatibility wall".

[Vincent Biret (baywet)]

ASP.NET Core 10 Preview 3 shipped yesterday, so I'm now up to preview.11. Due to breaking changes in subsequent previews there are constraints on how far forwards I can jump in my own code before I hit a "compatibility wall".

yes the goal is that once the initial file is merged we can:

1. enforce that any new breaking change PR also contains a modification to this file
2. work our way out of the "documentation debt" in multiple separate PRs (and of course, external contributions are always welcome)

[Vincent Biret (baywet)]

Martin Costello (@martincostello), now that this is merged, would you mind going ahead and proposing your changes as a PR please?