OpenAPI build-time generation's file destination is incorrect and causes build errors

[sander1095]

Description

Hi!

I ran into dotnet/aspnetcore#59157 . It correctly states the docs are incorrect:

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md#modifying-the-output-directory-of-the-generated-open-api-file

By default, the generated OpenAPI document will be emitted to the application's output directory. To modify the location of the emitted file, set the target path in the OpenApiDocumentsDirectory property.

<PropertyGroup>
  <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
</PropertyGroup>

The value of OpenApiDocumentsDirectory is resolved relative to the project file. Using the ./ value above will emit the OpenAPI document in the same directory as the project file.

Using this ./ path causes a build error. It should changed to . to build correctly.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/aspnetcore-openapi?view=aspnetcore-9.0&tabs=visual-studio#modifying-the-output-directory-of-the-generated-open-api-file

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/openapi/aspnetcore-openapi.md

Document ID

27bad30c-e0b4-10fb-b202-a29d4f8fad24

Article author

@captainsafia

Metadata

• ID: 27bad30c-e0b4-10fb-b202-a29d4f8fad24
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues

[Rick-Anderson]

@sander1095 what OS and version? What .NET version?

This happened on preview versions but was fixed in .NET 9 GA.

[sander1095]

Copied from the comment in the PR: #34509

@Rick-Anderson

WSL (Ubuntu 22.04)

sander@PC-Sander:~$ dotnet --info
.NET SDK:
 Version:           9.0.100
 Commit:            a2bc464e40
 Workload version:  9.0.100-manifests.6bf02610
 MSBuild version:   17.12.7+a2bc464e4

Runtime Environment:
 OS Name:     ubuntu
 OS Version:  22.04
 OS Platform: Linux
 RID:         ubuntu.22.04-x64
 Base Path:   /usr/lib/dotnet/sdk/9.0.100/

.NET workloads installed:
There are no installed workloads to display.
Configured to use loose manifests when installing new manifests.

Host:
  Version:      9.0.0
  Architecture: x64
  Commit:       a2bc464e40

.NET SDKs installed:
  9.0.100 [/usr/lib/dotnet/sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 9.0.0 [/usr/lib/dotnet/shared/Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 9.0.0 [/usr/lib/dotnet/shared/Microsoft.NETCore.App]

Other architectures found:
  None

Environment variables:
  Not set

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download

Windows 11 Pro (10.0.22631 Build 22631, 23H2)

.NET SDK:
 Version:           9.0.102
 Commit:            cb83cd4923
 Workload version:  9.0.100-manifests.4a54b1a6
 MSBuild version:   17.12.18+ed8c6aec5

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.22631
 OS Platform: Windows
 RID:         win-x64
 Base Path:   C:\Program Files\dotnet\sdk\9.0.102\

.NET workloads installed:
There are no installed workloads to display.
Configured to use loose manifests when installing new manifests.

Host:
  Version:      9.0.1
  Architecture: x64
  Commit:       c8acea2262

.NET SDKs installed:
  6.0.428 [C:\Program Files\dotnet\sdk]
  8.0.300-preview.24203.14 [C:\Program Files\dotnet\sdk]
  9.0.102 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 6.0.36 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 8.0.2 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 8.0.12 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 9.0.1 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 6.0.36 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.2 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.12 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 9.0.1 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.WindowsDesktop.App 6.0.36 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 8.0.2 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 8.0.12 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 9.0.1 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Other architectures found:
  x86   [C:\Program Files (x86)\dotnet]
    registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]

Environment variables:
  Not set

global.json file:
  Not found

Learn more:
  https://aka.ms/dotnet/info

Download .NET:
  https://aka.ms/dotnet/download

---

Building with ./

The final csproj

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

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

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

</Project>

Windows 11 Pro ❌

dotnet new webapi -f net9.0
dotnet add package Microsoft.Extensions.ApiDescription.Server -v 9.0.1 # Install the latest version from nuget
# Add <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory> to the csproj
dotnet build

# ERROR
PS C:\projects\Personal\temp6> dotnet build
Restore complete (0,3s)
  temp6 failed with 2 error(s) (2,1s) → bin\Debug\net9.0\temp6.dll
    C:\Users\stenb\.nuget\packages\microsoft.extensions.apidescription.server\9.0.1\build\Microsoft.Extensions.ApiDescription.Server.targets(68,5): error : Missing required option '--project'.
    C:\Users\stenb\.nuget\packages\microsoft.extensions.apidescription.server\9.0.1\build\Microsoft.Extensions.ApiDescription.Server.targets(68,5): error MSB3073: The command "dotnet "C:\Users\stenb\.nuget\packages\microsoft.extensions.apidescription.server\9.0.1\build\../tools/dotnet-getdocument.dll" --assembly "C:\projects\Personal\temp6\bin\Debug\net9.0\temp6.dll" --file-list "obj\temp6.OpenApiFiles.cache" --framework ".NETCoreApp,Version=v9.0" --output "C:\projects\Personal\temp6\" --project "temp6" --assets-file "C:\projects\Personal\temp6\obj\project.assets.json" --platform "AnyCPU" " exited with code 1.

Build failed with 2 error(s) in 2,6s

WSL (Ubuntu 22.04) ✅

dotnet new webapi -f net9.0
dotnet add package Microsoft.Extensions.ApiDescription.Server -v 9.0.1 # Install the latest version from nuget
# Add <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory> to the csproj
dotnet build

# SUCCESS
sander@PC-Sander:~/projects/temp$ dotnet build
Restore complete (0.5s)
  temp succeeded (2.6s) → bin/Debug/net9.0/temp.dll

Build succeeded in 3.4s

Building with .

The final csproj

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

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

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

</Project>

Windows 11 Pro ✅

dotnet new webapi -f net9.0
dotnet add package Microsoft.Extensions.ApiDescription.Server -v 9.0.1 # Install the latest version from nuget
# Add <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory> to the csproj
dotnet build

# SUCCESS
PS C:\projects\Personal\temp6> dotnet build
Restore complete (0,3s)
  temp6 succeeded (0,7s) → bin\Debug\net9.0\temp6.dll

Build succeeded in 1,2s

WSL (Ubuntu 22.04) ✅

dotnet new webapi -f net9.0
dotnet add package Microsoft.Extensions.ApiDescription.Server -v 9.0.1 # Install the latest version from nuget
# Add <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory> to the csproj
dotnet build

# SUCCESS
sander@PC-Sander:~/projects/temp$ dotnet build
Restore complete (0.5s)
  temp succeeded (2.6s) → bin/Debug/net9.0/temp.dll

Build succeeded in 3.4s

I hope this gives you all the info you need!

As far as I see it, this issue persists in .NET 9 GA but is fixed on both Windows and Ubuntu when using <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>, which is what this PR aims to fix in the docs.