Microsoft.Extensions.ApiDescription.Server : After build, OpenAPI specification file isn't present in the build result

[vernou]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I try to follow the documentation Generate OpenAPI documents at build-time, but the OpenAPI specification file isn't present in the build result.

I reproduce on Windows 10 and Windows 11 (I haven't tested it elsewhere).

Expected Behavior

The OpenAPI specification file is in the build result.

Steps To Reproduce

So the script :

dotnet new webapi --name MyApi --no-https --use-program-main --use-controllers
cd MyApi
dotnet add package Microsoft.Extensions.ApiDescription.Server
dotnet build

Then if we display the bin :

> dir bin\Debug\net9.0

 Volume in drive C has no label.
 Volume Serial Number is 60F0-FEC7

 Directory of C:\t\dotnte-poc\MyApi\bin\Debug\net9.0

05/12/2024  15:50    <DIR>          .
05/12/2024  15:50    <DIR>          ..
05/12/2024  15:50               127 appsettings.Development.json
05/12/2024  15:50               151 appsettings.json
29/10/2024  14:30           192 800 Microsoft.AspNetCore.OpenApi.dll
06/08/2024  10:15           239 024 Microsoft.OpenApi.dll
05/12/2024  15:50             2 235 MyApi.deps.json
05/12/2024  15:50             8 704 MyApi.dll
05/12/2024  15:50           145 408 MyApi.exe
05/12/2024  15:50            21 348 MyApi.pdb
05/12/2024  15:50               416 MyApi.runtimeconfig.json
05/12/2024  15:50                68 MyApi.staticwebassets.endpoints.json
              10 File(s)        610 281 bytes
               2 Dir(s)  98 535 710 720 bytes free

The file MyApi.json is missing.

---

But the file is correctly generated and present in obj :

>dir obj

 Volume in drive C has no label.
 Volume Serial Number is 60F0-FEC7

 Directory of C:\t\dotnte-poc\MyApi\obj

05/12/2024  15:50    <DIR>         .
05/12/2024  15:50    <DIR>         ..
05/12/2024  15:50    <DIR>         Debug
05/12/2024  15:50             2 982  MyApi.csproj.nuget.dgspec.json
05/12/2024  15:50             2 165  MyApi.csproj.nuget.g.props
05/12/2024  15:50               551   MyApi.csproj.nuget.g.targets
05/12/2024  15:50             1 730  MyApi.json                                 <<<<< Here
05/12/2024  15:50                38    MyApi.OpenApiFiles.cache
05/12/2024  15:50            20 520 project.assets.json
05/12/2024  15:50               581   project.nuget.cache
               7 File(s)         28 567 bytes
               3 Dir(s)  98 537 242 624 bytes free

Exceptions (if any)

No response

.NET Version

9.0.101

Anything else?

No response

[martincostello]

I think this is by design that it's in obj (I don't know why though).

There is an MSBuild property you can set to customise where it's written to: OpenApiDocumentsDirectory.

[vernou]

The doc says explicitly in the output directory (generally bin) :

So it's the documentation that's wrong?

---

OpenApiDocumentsDirectory work as expected, but how I can specify the output dir?
It try in csproj :

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiDocumentsDirectory>$(OutputDir)</OpenApiDocumentsDirectory>
  </PropertyGroup>

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

</Project>

And get the compilation error :

.nuget\packages\microsoft.extensions.apidescription.server\9.0.0\build\Microsoft.Extensions.ApiDescription.Server.targets(55,7): error MSB4184: The expression "[System.IO.Path]::GetFullPath('')" cannot be evaluated. The path is not of a legal form.

[martincostello]

Try OutputPath - I do this: https://github.com/martincostello/api/blob/ad179842be00bae2fa2da06b04ad28dd312ee6f9/src/API/API.csproj#L10

[vernou]

I get the same error with OutputPath. I tried also many properties from Common MSBuild project properties

From your example, how is defined ArtifactsPath?

[martincostello]

It's part of using the Artifacts Output feature: https://learn.microsoft.com/dotnet/core/sdk/artifacts-output

[vernou]

Ok, thank for your help.

[IsaacCloos]

I agree that they should update the docs to correctly list where the file is outputted to.

I'm working on a Vue+AspNet template project and here is my property group settings:

<PropertyGroup>
    <OpenApiDocumentsDirectory>../client/src/api</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocumentsOptions>--file-name openapi-schema</OpenApiGenerateDocumentsOptions>
  </PropertyGroup>

A second strange behavior I've found is if you delete this file and rebuild you won't get a new file until you've either changed something about your server code or cleaned your project. I would ideally like to recreate this file if it is missing regardless of the other incremental build optimizations dotnet uses.

[captainsafia]

I agree that they should update the docs to correctly list where the file is outputted to.

@IsaacCloos Would you be interested in opening a PR on the docs to tweak this? You're correct that the docs are currently incorrect about the default output directory.

A second strange behavior I've found is if you delete this file and rebuild you won't get a new file until you've either changed something about your server code or cleaned your project. I would ideally like to recreate this file if it is missing regardless of the other incremental build optimizations dotnet uses.

Yeah, unfortunately the current strategy is plagued with incrementally issues. :/

This is a good opportunity to dupe this bug report to #58353. The Microsoft.Extensions.ApiDescription.Server implementation predates the OpenAPI support we shipped in .NET 9 and was optimized for use with third-party libraries like Swashbuckle and NSwag. With the new built-in support, we're hoping to reconcile build-time generation into the M.A.OpenApi package and provide a more sensible configuration and execution behavior compared the existing approach.