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

sander1095 · 2025-01-16T15:42:58Z

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

The text was updated successfully, but these errors were encountered:

Rick-Anderson · 2025-01-29T21:25:33Z

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

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

sander1095 · 2025-01-29T22:35:43Z

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.

dotnetrepoman bot added aspnet-core/svc fundamentals/subsvc Source - Docs.ms Docs Customer feedback via GitHub Issue labels Jan 16, 2025

dotnet-policy-service bot added the ⌚ Not Triaged label Jan 16, 2025

sander1095 mentioned this issue Jan 16, 2025

Replace file destination instructions for OpenAPI build-time documentation so projects can build correctly #34509

Merged

Rick-Anderson self-assigned this Jan 30, 2025

Rick-Anderson added this to dotnet/AspNetCore.Docs January 2025 sprint Jan 30, 2025

github-project-automation bot moved this to 🔖 Ready in dotnet/AspNetCore.Docs January 2025 sprint Jan 30, 2025

Rick-Anderson closed this as completed in #34509 Jan 30, 2025

github-project-automation bot moved this from 🔖 Ready to ✅ Done in dotnet/AspNetCore.Docs January 2025 sprint Jan 30, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

sander1095 commented Jan 16, 2025 •

edited by dotnetrepoman bot

Loading

Rick-Anderson commented Jan 29, 2025 •

edited

Loading

sander1095 commented Jan 29, 2025

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

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

Comments

sander1095 commented Jan 16, 2025 • edited by dotnetrepoman bot Loading

Description

Page URL

Content source URL

Document ID

Article author

Metadata

Rick-Anderson commented Jan 29, 2025 • edited Loading

sander1095 commented Jan 29, 2025

Building with ./

Windows 11 Pro ❌

WSL (Ubuntu 22.04) ✅

Building with .

Windows 11 Pro ✅

WSL (Ubuntu 22.04) ✅

sander1095 commented Jan 16, 2025 •

edited by dotnetrepoman bot

Loading

Rick-Anderson commented Jan 29, 2025 •

edited

Loading