Microsoft.Extensions.ApiDescription.Server: Allow specifying --environment

[josundt]

Is there an existing issue for this?

• [X] I have searched the existing issues

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

I just added the Microsoft.Extensions.ApiDescription.Server package to our AspNetCore Web API project to automatically produce swagger JSON files as part of build.

The swagger generation in our solution depends on application settings (IConfiguration). Our swagger document defines and applies swagger security schemes, and the schemes include IdentityProvider URLs etc. - and these properties vary across different application environments and therefore need to be stored in configuration sources per environment.

When debugging the API locally from Visual Studio and accessing the swagger JSON file(s) through the swagger API endpoints, the Configuration provider includes appsettings.Development.json as a configuration source since the API launch settings sets the environment variable ASPNETCORE_ENVIRONMENT to "Development" before starting up.

I can alternatively control the environment name using command line when running the API project: dotnet run --environment Development

After adding the Microsoft.Extensions.ApiDescription.Server package, the dotnet build command will cause this new package execute the API project's code to generate the swagger data; but there is unfortunately no way to pass the "environment name" to the API project when it's being executed. (The only way is to remember to always set the ASPNETCORE_ENVIRONMENT variable before dotnet build).

The missing feature: I can not control the environment name (and thereby the configuration sources) used when the swagger is generated.

Describe the solution you'd like

Proposal: Add support for a new csproj/msbuild property OpenApiGenerateEnvironment which will allow us to define the environment name to pass when executing the API project to generate the JSON during build.

The ability to control the environment name and thereby configuration sources when generating swagger during build is a feature that will add great value to the package. I hope it will get priority.

This is how I would prefer it to work (notice the new proposed OpenApiGenerateEnvironment property):

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <!-- ... -->
    <OpenApiDocumentsDirectory>$(BaseIntermediateOutputPath)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
    <OpenApiGenerateEnvironment>Development</OpenApiGenerateEnvironment>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="8.0.3">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>
</Project>

Additional context

No response

[captainsafia]

@josundt Thanks for filing this issue!

To resolve this issue, we'll need to set the MSBuild property and then pass it into the GetDocumentWorker via a CLI flag here.

I dunno if I'll be able to get to this as part of the recent OpenAPI work that we are doing but I'd be glad to review a PR!

[pinkfloydx33]

We needed something similar, except we needed more than just the environment name, additionally requiring a few other configuration options. We ending up overwriting the msbuild target that's invoking this (GenerateOpenApiDocuments) to do the very same thing but also passing in the EnvironmentVariables attribute to the Exec task. Something like that would be more general purpose and would help support any other settings people could need.

[RidaEn-nasry]

@captainsafia would like to look into this one if someone else isn’t already ?

[captainsafia]

@RidaEn-nasry Yes, PRs welcome. None have been open on this front AFAIK.

[MattyLeslie]

@RidaEn-nasry are you currently working on this ?

[MattyLeslie]

Hey @captainsafia. Would passing the environment name be sufficient here or would it be worth looking into support other environment variables too?

[captainsafia]

@MattyLeslie For the purposes of this bug, I think passing in just the environment name should be sufficient. I'd prefer to be more constrained about what we pass to the app instance that gets instantiated and run.

[diegosasw]

is there any current recommended way to discriminate explicit app launch from build-related-launch (i.e: the implicit launch used to produce the open api json)? Is there any way to know at Program.cs which kind of launch is it, in order to configure real services or mocks? Or is it an env variable the only way?

// isn't there any way to configure environment value or any other flag?
var isOpenApiExecution = builder.Environment.IsEnvironment("ApiDescription");
if (!isOpenApiExecution)
{
    throw new Exception("Sample exception to demonstrate that Api Description build should skip this");
}

[captainsafia]

@diegosasw Unfortunately not, until this issue is resolved you can write a helper function like the following:

using System.Reflection;

public static bool IsOpenApiExecution()
  => Assembly.GetEntryAssembly()?.GetName().Name == "GetDocument.Insider";

[diegosasw]

Assembly.GetEntryAssembly()?.GetName().Name == "GetDocument.Insider";

Thanks for the workaround! It works well for the purpose.

[imparikshith]

Is anybody contributing to this issue? if not I would like to contribute.

[ldsenow]

@captainsafia Hi, i have created a PR for this environment passing issue. Are you able to give some feedback?

[ldsenow]

looks like this repo isnt having human resource to maintain. All robots checks and reviews.

[imparikshith]

Hi, I would like to contribute to resolving this issue if it's still open and available. Please let me know how I can get started or if there are specific areas where help is needed. Thank you!

[ldsenow]

Hi, I would like to contribute to resolving this issue if it's still open and available. Please let me know how I can get started or if there are specific areas where help is needed. Thank you!

I have made a PR already, however, there is no feedback altogether. That is why I see this isn't actively maintained.