[.NET 9]: Refactor and revise OpenAPI docs

[captainsafia]

We're making some significant changes to the OpenAPI area in .NET 9. Namely:

• Adding built-in support for OpenAPI document generation
• Updating the web API templates to take advantage of the built-in support

As part of this, we'll want to refactor the docs on OpenAPI to reflect the state of the new universe.

AFAICT, we reference OpenAPI in a few pages in the docs:

• OpenAPI support in minimal APIs
• Swagger/OpenAPI under controller-based APIs
  • Includes "Getting started with NSwag" and "Getting started with Swashbuckle" sub-pages
• .NET OpenAPI tool reference
• Using OpenAPI with gRPC JSON transcoding
• Getting started with Swashbuckle and ASP.NET Core sample
• Generate a REST API client in a build

As part of this work, I'm recommending a revised header structure for our OpenAPI-related docs.

• Controller-based APIs
  • OpenAPI
    • Overview
    • Getting started with Microsoft.AspNetCore.OpenApi
    • Getting started with Swashbuckle
    • Getting started with NSwag
    • Working with OpenAPI at build-time
• Minimal APIs
  • OpenAPI
    • Overview
    • Getting started with Microsoft.AspNetCore.OpenApi
    • Getting started with Swashbuckle
    • Getting started with NSwag
    • Working with OpenAPI at build-time

The content under each of these pages should be the same, which conditional headers that allows us to show controller and minimal API specific code when necessary.

We'll also need to go in and revise any code blocks that reference UseSwagger/UseSwaggerUi to reference the new built-in APIs.

We'll probably want to have the first pass of this done to align with the preview4 release coming up in May. I'll create some draft content on the new APIs that we can incorporate here.

cc: @Rick-Anderson @tdykstra @JeremyLikness @mikekistler

---

Associated WorkItem - 302692

[captainsafia]

@martincostello What are your thoughts on the current Swashbuckle doc page (ref)? I think most of the content on there is accurate but some of the additional resources might be updated.

@RicoSuter How about the NSwag page (ref)? I think the code generation section could use some sprucing. We don't mention the NSwag client generation via VS Connected services at all. And perhaps the screenshots need updating?

[martincostello]

@captainsafia Once we ship our 6.6.0 release with net8.0 support (in the next week or so 🤞) I was planning on reviewing the existing content to see what might need tweaking. At a minimum I was going to propose the "doesn't work with .NET 8" notes be removed.

[captainsafia]

At a minimum I was going to propose the "doesn't work with .NET 8" notes be removed.

That sounds like a good idea to me! What are your thoughts on the amount of content that is on there?

I'm not sure what the right balance between docs on this page and those we would link to externally in the Swashbuckle repo/elsewhere.

[martincostello]

I think the level of content there is fine - it seems to cover all the entry-level scenarios with a few troubleshooting hints. It might duplicate stuff that is (or should) be in our README, but I don't think there's anything in there that's out-of-date or incorrect from a quick scroll through.

I did notice there's a link off to https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1920 at the end of the document, which is resolved for 6.6.0, so that can be removed once we ship that too.

[captainsafia]

@martincostello Great! TYSM for your help here.

[wadepickett]

@captainsafia and @mikekistler, I would like to update these two tutorials right away for .NET 9:

Tutorial: Create a minimal API with ASP.NET Core | Microsoft Learn

Tutorial: Create a web API with ASP.NET Core | Microsoft Learn

Question: For the Visual Studio Code targeted version of those tutorials for .NET 9, would it be OK to use the Scalar.AspNetCore package for generating UI, pointing it to the OpenAPI generated .json output? (This would be enabled for the dev environment only as was also pointed out here: Work with OpenAPI documents | Microsoft Learn

I could use curl to avoid a UI package, but then the topic gets a fair bit longer as I walk them through how to create those commands. Using a UI really simplifies these two getting started topic for the VSC versions.

For tutorials targeted at Visual Studio I would continue to use the Endpoints Explorer + .http files.

[mikekistler]

@wadepickett I think either Scalar or SwaggerUI would be fine to use in the VSCode version of the tutorials. I know @captainsafia prefers Scalar, but .NET developers are very familiar with SwaggerUI and might find that more natural.

[Rick-Anderson]

@captainsafia prefers Scalar, but .NET developers are very familiar with SwaggerUI and might find that more natural.

For SwaggerUI, they can follow the .NET 8 version , so my vote for .NET 9 is Scalar.