Missing documentation about using OpenAPI together with versioning

[sander1095]

Description

The page describes generating multiple OpenAPI documents, but one of the most popular approaches is to use ASP.NET API Versioning together with the v{version}.json URL to end up with different OpenAPI documents.

This is not a part of the OpenAPI documentation. Would the team welcome a PR (because of Hacktoberfest) for this? I understand that the ASP.NET API Versioning project might not have a current maintainer, and therefore I thought it'd be worth asking if the team wants to feature this project in the docs.

To me, this is always one of the few things that Microsoft Learn lacked. Having to use StackOverflow/blog posts/AI to get this to work was always a bit annoying. That's why I'd love to add some documentation and a basic setup for minimal API's and controllers, to allow people to get started.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-10.0&tabs=visual-studio%2Cvisual-studio-code

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md

Document ID

27bad30c-e0b4-10fb-b202-a29d4f8fad24

Platform Id

11e029f8-4c25-d943-fe65-31bfcaf35e2b

Article author

@captainsafia

Metadata

• ID: 27bad30c-e0b4-10fb-b202-a29d4f8fad24
• PlatformId: 11e029f8-4c25-d943-fe65-31bfcaf35e2b
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues

[guardrex]

Thanks for the offer, @sander1095. Let's see what @captainsafia and @danroth27 think about this.

[danroth27]

@mikekistler I think this is your call.

[mikekistler]

@sander1095 I agree this is a gap and I was hoping to address it with a blog post on how to use Asp.Versioning with the built-in OpenAPI generation introduced in .NET 9. Sadly other matters have intruded and I haven't had time to write that blog post yet. I think this should be a blog post rather than part of the official docs, and if you are willing to write a post for this I think we can publish it in the .NET blog so that it gets wide visibility.

[guardrex]

Thanks @mikekistler.

I'll go ahead and close this, but please feel free @sander1095 to continue your convo with @mikekistler here.

[sander1095]

I'll definitely write it soon! Thanks @mikekistler !