Skip to content

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

New issue
New issue
Closed
#34509
Closed
OpenAPI build-time generation's file destination is incorrect and causes build errors#34508
#34509
Assignees
Rick-Anderson
Labels
⌚ Not TriagedSource - Docs.msDocs Customer feedback via GitHub Issueaspnet-core/svcfundamentals/subsvc
@sander1095

Description

@sander1095
sander1095
opened on Jan 16, 2025

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

Activity

dotnetrepoman
added
aspnet-core/svc
fundamentals/subsvc
Source - Docs.msDocs Customer feedback via GitHub Issue
on Jan 16, 2025
dotnet-policy-service
added
⌚ Not Triaged
on Jan 16, 2025
sander1095
mentioned this on Jan 16, 2025
Rick-Anderson

Rick-Anderson commented on Jan 29, 2025

@Rick-Anderson
Rick-Anderson
on Jan 29, 2025 · edited by Rick-Anderson
Contributor

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

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

sander1095

sander1095 commented on Jan 29, 2025

@sander1095
sander1095
on Jan 29, 2025
ContributorAuthor

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.

Rick-Anderson
self-assigned this
on Jan 30, 2025
Rick-Anderson
added this to dotnet/AspNetCore.Docs January 2025 sprinton Jan 30, 2025
github-project-automation
moved this to 🔖 Ready in dotnet/AspNetCore.Docs January 2025 sprinton Jan 30, 2025
Rick-Anderson
closed this as completedin #34509on Jan 30, 2025
github-project-automation
moved this from 🔖 Ready to ✅ Done in dotnet/AspNetCore.Docs January 2025 sprinton Jan 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

⌚ Not TriagedSource - Docs.msDocs Customer feedback via GitHub Issueaspnet-core/svcfundamentals/subsvc

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions
    OpenAPI build-time generation's file destination is incorrect and causes build errors · Issue #34508 · dotnet/AspNetCore.Docs