"dotnet new webapiaot" should include OpenAPI support

[sander1095]

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!

[sander1095]

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

[captainsafia]

@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.

[sander1095]

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]

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

[sander1095]

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