Microsoft.Extensions.ApiDescription.Server doesn't use the proper environment which causes the build to fail.

[nphmuller]

Most if this is a guess by inspecting the source code, since ApiDescription.Server doesn't seem to be documented anywhere formally (or I cannot find the documentation).

I guess my main question is: What is the recommended way to get Microsoft.Extensions.ApiDescription.Server to work? Especially in combinations with projects like Swashbuckle.

When adding Microsoft.Extensions.ApiDescription.Server to a project (which is necessary for the latest Swashbuckle.AspNetCore version (5.0.0-rc3) a new build target is executed. I guess this target starts an instance of the application and infers ApiExplorer configuration from it.

This causes the build to fail in certain circumstances if the application startup relies on certain app settings:

• When running locally my app relies on the settings in appsettings.development.json, but the environment is not set by ApiDescription.Server. Because of this some settings are missing, causing the app startup (during the build) to fail.
• When building for Production, the settings are only set during deployment, which happens a while after build. This is another reason why some settings might be missing and the build will fail.

I'm not really sure what ApiDescription.Server does during build, but if it relies on application startup the result might differ between environments (dev, staging, production). If the same build artifacts are used in staging and production ApiDescription.Server might have generated the incorrect information.

An Example startup configuration which demonstraties this is:

public void ConfigureServices(IServiceCollection services)
{
    var cert = GetCert(options.CertThumbprint);
    services.AddDataProtection()
        .ProtectKeysWithCertificate(cert);
}

appsettings.json doesn't contain the CertThumbprint setting, but appsettings.development.json does. And during a production build CertThumbprint is only set during deployment.

This is based on all the 3.0 RTM bits and Visual Studio 16.3.0 (although I guess the latter doesn't matter much).

[mkArtakMSFT]

Thanks for contacting us, @nphmuller.
There are certain requirements this feature has, which projects should comply with to work properly. We're going to add documentation for the feature by the end of the next week listing all these requirements.
As for now, your ConfigureServices method uses certificate which requires access that that cert at build time for document generation. If you don't wish to do that, then you can opt out from the automatic document generation feature by setting the OpenApiGenerateDocumentsOnBuild property to false in your csproj file:

<PropertyGroup>
    <OpenApiGenerateDocumentsOnBuild>false</OpenApiGenerateDocumentsOnBuild>
</PropertyGroup>

As for the documentation, we're tracking that work as part of: dotnet/AspNetCore.Docs#8462