Skip to content

"dotnet new webapiaot" should include OpenAPI support #59564

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.

Sign up for GitHub

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

Jump to bottom
Closed
1 task done
sander1095 opened this issue Dec 19, 2024 · 5 comments · Fixed by #60337 or #61302
Closed
1 task done

"dotnet new webapiaot" should include OpenAPI support #59564

sander1095 opened this issue Dec 19, 2024 · 5 comments · Fixed by #60337 or #61302
Labels
area-minimal Includes minimal APIs, endpoint filters, parameter binding, request delegate generator etc feature-openapi NativeAOT
Milestone
.NET 10 Planning

Comments

@sander1095
Copy link
Contributor

Is there an existing issue for this?

  • I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

When I try to create an ASP.NET Core project with AOT support, I can use dotnet new webapiaot. I can add the --help flag to see available options:

# dotnet new webapiaot --help
# Truncated...
  --exclude-launch-settings        Whether to exclude launchSettings.json from the generated template.
                                   Type: bool
                                   Default: false
  -f, --framework <net8.0|net9.0>  The target framework for the project.
                                   Type: choice
                                     net9.0  Target net9.0
                                     net8.0  Target net8.0
                                   Default: net9.0
  --no-restore                     If specified, skips the automatic restore of the project on create.
                                   Type: bool
                                   Default: false
  --use-program-main               Whether to generate an explicit Program class and Main method instead of top-level statements.
                                   Type: bool
                                   Default: false

That's quite limited!

I can also create a project without AOT support by using dotnet new webapi. This has a lot more options:

Click to view code 
  -au, --auth <IndividualB2C|None|SingleOrg|Windows>                  The type of authentication to use
                                                                      Type: choice
                                                                        None           No authentication
                                                                        IndividualB2C  Individual authentication with Azure AD B2C
                                                                        SingleOrg      Organizational authentication for a single tenant
                                                                        Windows        Windows authentication
                                                                      Default: None
  --aad-b2c-instance <aad-b2c-instance>                               The Azure Active Directory B2C instance to connect to (use with IndividualB2C auth).
                                                                      Type: string
                                                                      Default: https://qualified.domain.name.b2clogin.com/
  -ssp, --susi-policy-id <susi-policy-id>                             The sign-in and sign-up policy ID for this project (use with IndividualB2C auth).
                                                                      Type: string
                                                                      Default: b2c_1_susi
  --aad-instance <aad-instance>                                       The Azure Active Directory instance to connect to (use with SingleOrg auth).
                                                                      Type: string
                                                                      Default: https://login.microsoftonline.com/
  --client-id <client-id>                                             The Client ID for this project (use with SingleOrg or IndividualB2C auth).
                                                                      Type: string
                                                                      Default: 11111111-1111-1111-11111111111111111
  --domain <domain>                                                   The domain for the directory tenant (use with SingleOrg or IndividualB2C auth).
                                                                      Type: string
                                                                      Default: qualified.domain.name
  --default-scope <default-scope>                                     The API scope the client needs to request to provision an access token. (use with IndividualB2C, SingleOrg).
                                                                      Type: string
                                                                      Default: access_as_user
  --tenant-id <tenant-id>                                             The TenantId ID of the directory to connect to (use with SingleOrg auth).
                                                                      Type: string
                                                                      Default: 22222222-2222-2222-2222-222222222222
  -r, --org-read-access                                               Whether or not to allow this application read access to the directory (only applies to SingleOrg auth).
                                                                      Type: bool
                                                                      Default: false
  --exclude-launch-settings                                           Whether to exclude launchSettings.json in the generated template.
                                                                      Type: bool
                                                                      Default: false
  --no-https                                                          Whether to turn off HTTPS. This option only applies if IndividualB2C, SingleOrg, or MultiOrg aren't used for --auth.
                                                                      Type: bool
                                                                      Default: false
  -uld, --use-local-db                                                Whether to use LocalDB instead of SQLite. This option only applies if --auth Individual or --auth IndividualB2C is specified.
                                                                      Type: bool
                                                                      Default: false
  -f, --framework <net5.0|net6.0|net7.0|net8.0|net9.0|netcoreapp3.1>  The target framework for the project.
                                                                      Type: choice
                                                                        net9.0         Target net9.0
                                                                        net8.0         Target net8.0
                                                                        net7.0         Target net7.0
                                                                        net6.0         Target net6.0
                                                                        net5.0         Target net5.0
                                                                        netcoreapp3.1  Target netcoreapp3.1
                                                                      Default: net9.0
  --no-restore                                                        If specified, skips the automatic restore of the project on create.
                                                                      Type: bool
                                                                      Default: false
  --called-api-url <called-api-url>                                   URL of the API to call from the web app. This option only applies if --auth SingleOrg or --auth IndividualB2C is specified.
                                                                      Type: string
                                                                      Default: https://graph.microsoft.com/v1.0
  --calls-graph                                                       Specifies if the web app calls Microsoft Graph. This option only applies if --auth SingleOrg is specified.
                                                                      Type: bool
                                                                      Default: false
  --called-api-scopes <called-api-scopes>                             Scopes to request to call the API from the web app. This option only applies if --auth SingleOrg or --auth IndividualB2C is specified.
                                                                      Type: string
                                                                      Default: user.read
  --no-openapi                                                        Disable OpenAPI (Swagger) support
                                                                      Type: bool
                                                                      Default: false
  --use-program-main                                                  Whether to generate an explicit Program class and Main method instead of top-level statements.
                                                                      Type: bool
                                                                      Default: false
  -controllers, --use-controllers                                     Whether to use controllers instead of minimal APIs. This option overides the value specified by --minimal.
                                                                      Type: bool
                                                                      Default: false
  -minimal, --use-minimal-apis                                        Whether to use minimal APIs instead of controllers.
                                                                      Type: bool
                                                                      Default: false

The problem is that the AOT template doesn't have OpenAPI support by default, while the non-AOT version does support OpenAPI by default.

This is understandable, as .NET 8 didn't contain an AOT compatible OpenAPI implementation. However, NET 9 received improved OpenAPI support with AOT support: https://devblogs.microsoft.com/dotnet/dotnet9-openapi/.

This is not included by default in the .NET 9 webapiaot template, nor is it a flag like it is for dotnet new webapi (--no-openapi).
I understand there are a smaller amount of supported flags as AOT support is quite new, but I would like to see it added.

Describe the solution you'd like

OpenAPI is important for complex API's or API's that are consumed by API clients, like front-ends or other API's. If it is supported for non-aot projects, I would like to see it supported for AOT projects, too!

Additional context

I wouldn't mind creating a PR myself if the team agrees this could be useful!
@dotnet-issue-labeler dotnet-issue-labeler bot added the needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically label Dec 19, 2024
@sander1095
Copy link
Contributor Author

If we're going to implement this, we should also update the docs that currently mention you need to add the package yourself:

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-9.0&tabs=visual-studio#trimming-and-native-aot

@martincostello martincostello added area-minimal Includes minimal APIs, endpoint filters, parameter binding, request delegate generator etc and removed needs-area-label Used by the dotnet-issue-labeler to label those issues which couldn't be triaged automatically labels Dec 19, 2024
@captainsafia
Copy link
Member

@sander1095 Thanks for filing this issue!

I had mentally flagged adding in OpenAPI support to the Web API AoT template in .NET 9 but didn't do the legwork on filing an issue/doing the work.

I'm happy to do this in .NET 10.

One thing to note is that we're currently in the process of updating to the next major version of the OpenAPI.NET library to support OpenAPI 3.1 which regressed its AoT support. We'll want to close the loop on that before updating the templates for .NET 10.

@captainsafia captainsafia added this to the .NET 10 Planning milestone Dec 20, 2024
@sander1095
Copy link
Contributor Author

sander1095 commented Dec 20, 2024 •
edited
Loading

So you're saying you'll be implementing it? I would also like to do it, as mentioned in the description. :)

If you'd also welcome a community contribution - after AOT support is brought back - tag me and I'll get started on it? :)

@captainsafia
Copy link
Member

Community contribution definitely welcome! I'll post on this issue once AoT support is back again and we can update the templates.

@sander1095
Copy link
Contributor Author

I've heard from Safia that this issue can now be worked on. I'm working on this now :)

This was referenced Feb 12, 2025
Merged
Closed
sander1095 added a commit to sander1095/aspnetcore that referenced this issue Mar 3, 2025
@sander1095
Merge branch 'main' into dotnetGH-59564-webapiaot-openapi
98332af
@sander1095 sander1095 mentioned this issue Apr 3, 2025
Merged
4 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
area-minimal Includes minimal APIs, endpoint filters, parameter binding, request delegate generator etc feature-openapi NativeAOT
Projects
None yet
Milestone
.NET 10 Planning
3 participants
@martincostello @captainsafia @sander1095