-
Notifications
You must be signed in to change notification settings - Fork 10k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Use built-in OpenAPI support in templates #55343
Conversation
How come |
Moving forward, we don't need to follow this strategy. Instead, |
551ee6a
to
f35b58c
Compare
This should also be removed Line 328 in 08e84a2
|
I have a few questions
|
There will be no changes to the AoT project template at the moment. However, we expect the new implementation to be AoT friendly for minimal APIs.
We don't anticipate bundling Swagger UI in ASP.NET Core as part of this work. I'll update the launch settings to reflect this. We're investigating ways to provide a dev-time UI for viewing the generated OpenAPI documents that doesn't require bundling Swagger UI in the core framework. |
Sometimes we need the ui not just for development, but even in production environments |
You'll still be able to include Swagger UI independently for your production scenarios. Swagger UI's web assets can be configured to point at the OpenAPI document that is generated by ASP.NET Core. You can view an example of this in the sample app used for testing. Note: you'll want to be cautious about configuring Swagger UI correctly so that you're not unintentionally leaking OAuth client secrets, limiting XSS risks, and placing the UI endpoint behind authentication if necessary. |
Maybe I'd prefer MapSwaggerUi to be part of the framework, rather than everyone implementing it |
The Also, it's possible to use the Swagger UI bundled in Swashbuckle and NSwag and point them to the OpenAPI document that is generated by the framework so the re-implementation cost is not as extreme since it already exists in other packages. |
If I continue to use Swashbuckle or NSwag, they both provide document generation themselves, Why should I use the framework-generated OpenAPI documentation? I think the framework should provide a complete experience, rather than relying on external packages |
Each implementation doesn't generate the same document. The goal with the built-in support is to provide a high-quality document that takes advantage of the fact that doc generation lives closer to the framework. Anyhow, thanks for posting your comment on the issue. Let's continue the conversation there. 😄 |
The Swashbuckle.AspNetCore.SwaggerUI package doesn't depend on any of the Swashbuckle generation code, and essentially just distributes swagger-ui itself. Repackaging it again in a third package wouldn't add any value other than being "from Microsoft" for those eschew non-Microsoft packages for whatever reasons they may have. It's also minimal effort to provide your own one-page of HTML that consumes swagger-ui directly from something such as cdnjs if you don't want a NuGet package to provide it for you. NSwag/Swashbuckle can easily co-exist with the new in-box OpenAPI support and the ASP.NET Core team can spend their finite development time on areas they can differentiate or expand on (schemas, native AoT support). |
But the project template went from the original direct launch swagger ui to the current open.json, A disruptive change to the user experience can make the user feel overwhelmed, and it would be better to explain a return to the original experience. |
@Varorbc I hear you on the concern around the experience break here. It's definitely something that was considered as part of this decision. However, there are ways to solve that problem that don't require the framework to bundle Swagger UI (and build an API layer around it).
FWIW, this change modifies the templates so that it launches the |
It would be better if you had documentation to explain this, or in template |
Yes, the revamped docs for OpenAPI will include information on this. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good! 👍
Just need to fix the short link.
src/ProjectTemplates/Web.ProjectTemplates/content/WebApi-CSharp/Program.Main.cs
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks great Safia!
d98d284
to
9b0cb77
Compare
Part of #46349.
Microsoft.AspNetCore.OpenApi
for document generation whenEnableOpenApi=true
WithOpenApi
calls on endpointslaunchUrl
for projects wereEnableOpenApi=true