[Epic] OpenAPI in .NET 7

[rafikiassumani-msft]

(*) ‼️ = Prevents users from successfully using OpenAPI, 🔨 = Improves the experience for using OpenAPI
S = A few hours
M = A few days
L = About a week
XL = Multiple weeks

Issue	Category	Impact (*)	Priority	Size	Status
Route constraints don't produce appropriate information in OpenAPI schema (#36525)	aspnetcore-bugs	‼️	P0	M	✅ (7.0-preview1)
ASP.NET Core templates that include both Open API and Authentication should include scaffolding for Swagger to authenticate users (#36185)	aspnetcore-features	🔨	P1	S	❌ Superseded by #39761
Support Deprecated in Minimal APIs for Open API (#35091)	aspnetcore-features	🔨	P2	S	✅ (7.0-preview4)
Support setting server on PathItem or Operation for each endpoint/controller/action	aspnetcore-features	‼️	P1	S	✅ (7.0-preview4)
Respect EndpointGroupName attributes in MVC ApiExplorer (#35055)	aspnetcore-bugs	‼️	P0	S	✅ (7.0-preview1)
Support minimal APIs in NSwag (RicoSuter/NSwag#3560)	partner-features	🔨	P1	M	✅ (7.0-preview1)
Automatically set endpoint metadata for minimal APIs (#34544)	aspnetcore-features	🔨	P1	M
Create an analyzer to help verify and fix endpoint metadata of minimal APIs (#34543)	aspnetcore-features, analyzers	🔨	P1	L
Support authentication and authorization in OpenAPI (#34546)	aspnetcore-features	‼️	P0	L	❌ Closed as a dupe of #39761
DateOnly and TimeOnly are displayed as complex objects in open-api schemas rather simple string (#37045)	aspnetcore-bugs	🔨	P2	S	❌ DateOnly and TimeOnly not supported by JSON schema
Generating REST Clients for .NET Minimal / Web API APIs (#36636)	aspnetcore-features	🔨	P1	XL
API analyzers should support undeclared status codes (#15385)	aspnetcore-bugs, analyzers	🔨	P3	M
API analyzer doesn't recognize ControllerBase.ValidationProblem (#6061)	aspnetcore-bugs, analyzers	🔨	P3	M
ProblemDetails is not returned for 404NotFound and 500Exception (#4953)	aspnetcore-bugs	🔨	P3	S	❌ Not actually OpenAPI
Mvc.Api.Analyzers not recognizing methods from a Base Class (#4410)	aspnetcore-bugs	🔨	P3	M
Security schemes cannot be generated for individual endpoints/actions	aspnetcore-bugs	‼️	P0	M
Descriptions and examples cannot be set for endpoints or controllers (#37906)	aspnetcore-bugs	‼️	P0	S	✅ (7.0-preview4)
Share more RequestDelegateFactory.CreateArgument logic (#33644)	aspnetcore-bugs	🔨	P2	M

[mholec]

I am still surprised why so much effort is put into generating documentation for the OAS. Considering the popularity of approaches like microservices and API gateways, generating documentation generally misses the point. Generated documentation never reaches the quality of the specification and reflects implementation errors. Generated documentation is unusable in practice for automation, mocking and testing. The specification first approach has been a trend for several years. How can Minimal APIs be minimalistic when half of the extension methods are used for swashbuckle instructions? In my opinion, a developer should program functionality, not instructions to generate documentation.

[captainsafia]

I am still surprised why so much effort is put into generating documentation for the OAS. Considering the popularity of approaches like microservices and API gateways, generating documentation generally misses the point. Generated documentation never reaches the quality of the specification and reflects implementation errors. Generated documentation is unusable in practice for automation, mocking and testing. The specification first approach has been a trend for several years. How can Minimal APIs be minimalistic when half of the extension methods are used for swashbuckle instructions? In my opinion, a developer should program functionality, not instructions to generate documentation.

Although not outlined in this issue, our future direction rests on using a singular WithOpenApi extension method for modifying OpenApi-related details. We recognize that the plethora of extensions was problematic and switched to this design approach.

We've also got issues tracked here to generate more of the documentation by default. The extension methods are only there for explicitly overriding generated annotations.

[ghost]

Thanks for contacting us.

We're moving this issue to the .NET 8 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[captainsafia]

@rafikiassumani-msft What are your thoughts on closing this and creating a new epic for for .NET 8?