Add docs on Microsoft.AspNetCore.OpenApi

[captainsafia]

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/fundamentals/minimal-apis/aspnetcore-openapi.md	aspnetcore/fundamentals/minimal-apis/aspnetcore-openapi

[ron-zhong]

Well done!! :) What a remarkable milestone. Looking forward to seeing the completed doc.

If the upcoming doc can cover the topics about how to setup auth schemes that would be really great!!

Previously with SwaggerUI, I always needed to setup the OIDC resource owner password grant or AuthZ+PKCE grant flows in order to perform some manual testing with IDP server.

Ref: https://stackoverflow.com/questions/57585888/how-to-do-oauth2-authorization-in-asp-net-core-for-swagger-ui-using-swashbuckle

Hope that will be something we can easily achieve with the new OpenAPI offering in .NET 9. Thank you very much.

[captainsafia]

@ron-zhong Thanks for the feedback! I've added a sample that shows how to register authentication schemes globally using document transformers.

Admittedly, the built-in support doesn't move the needle on making this process more seamless. You still have to manually configure the schemes yourself.

If you're interested in efforts to make this process more seamless, check out dotnet/aspnetcore#39761. I shared some notes there on prototyping I've done in the past to make it easier to introspect auth configurations in an application. It's not super trivial and given the sensitive of authentication it's one of those things that you really have to get right. I dunno that we'll do something in this area for .NET 9 but it is something I've thought about in the past.

[captainsafia]

@tdykstra @Rick-Anderson @mikekistler @JeremyLikness I think there's enough content here to kick-off some review for it. Pardon any rawness in the content, I optimized for iterating early and often on this content as opposed to waiting to hit a perfect state. 😄

[Rick-Anderson]

@captainsafia I was going to PR this PR as I have many minor editorial edits but given this is good enough I think we should merge and then I can quickly PR the topic with my changes and have @tdykstra review them. Should I make any technical changes I'll mention you and the other technical folks.

[Rick-Anderson]

@JeremyLikness @mikekistler can one of you approve the code so we can merge this and then @tdykstra and I will do a quick cleanup right after.

[mikekistler]

Looks good! 👍

I left a bunch of very minor suggestions that you are free to ignore if you think they are misguided.