[.NET 10] Generating OpenAPI spec in `yaml` format seems to be broken

[erwinkramer]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Generating yaml docs for an OpenAPI spec does not seem to be working.

Expected Behavior

No response

Steps To Reproduce

https://github.com/erwinkramer/bank-api/tree/feature/dotnet10 is the project i'm testing it on

Change app.MapOpenApi("/openapi/{documentName}.json"); to

app.MapOpenApi("/openapi/{documentName}.yaml");
or
app.MapOpenApi("/openapi/{documentName}.yml");

As far as i know that's the only thing i should have to do.

My project file for generation looks like this:

 <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>../Specs.Generated</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocumentsOptions>--file-name openapi_v1</OpenApiGenerateDocumentsOptions>
  </PropertyGroup>

  <ItemGroup>
    <!-- for OpenApi spec generation -->
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="10.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

Exceptions (if any)

No exceptions, just these normal seeming logs when building (i still get the Index was outside the bounds of the array but that is related to #56831, i believe):

dotnet build C:\Users\erwin\GitHub Projects\bank-api\BankApi.sln /target:BankApi_Service_Stable /property:GenerateFullPaths=true /consoleloggerparameters:NoSummary /p:Configuration=Debug /p:Platform="Any CPU" 
C# extension build result service is available.
  Determining projects to restore...
  Restored C:\Users\erwin\GitHub Projects\bank-api\BankApi.Core\BankApi.Core.csproj (in 757 ms).
  Restored c:\Users\erwin\GitHub Projects\bank-api\BankApi.Tests\BankApi.Tests.csproj (in 756 ms).
  Restored c:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Beta\BankApi.Service.Beta.csproj (in 757 ms).
  Restored C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\BankApi.Service.Stable.csproj (in 757 ms).
  1 of 5 projects are up-to-date for restore.
C:\Program Files\dotnet\sdk\10.0.100-preview.6.25358.103\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.RuntimeIdentifierInference.targets(335,5): message NETSDK1057: You are using a preview version of .NET. See: https://aka.ms/dotnet-support-policy [C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\BankApi.Service.Stable.csproj]
C:\Program Files\dotnet\sdk\10.0.100-preview.6.25358.103\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.RuntimeIdentifierInference.targets(335,5): message NETSDK1057: You are using a preview version of .NET. See: https://aka.ms/dotnet-support-policy [C:\Users\erwin\GitHub Projects\bank-api\BankApi.Core\BankApi.Core.csproj]
  BankApi.Core -> C:\Users\erwin\GitHub Projects\bank-api\BankApi.Core\bin\Debug\net10.0\BankApi.Core.dll
CSC : warning AD0001: Analyzer 'Microsoft.AspNetCore.Analyzers.RouteHandlers.RouteHandlerAnalyzer' threw an exception of type 'System.IndexOutOfRangeException' with message 'Index was outside the bounds of the array.'. [C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\BankApi.Service.Stable.csproj]
CSC : warning AD0001: Analyzer 'Microsoft.AspNetCore.Analyzers.RouteHandlers.RouteHandlerAnalyzer' threw an exception of type 'System.IndexOutOfRangeException' with message 'Index was outside the bounds of the array.'. [C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\BankApi.Service.Stable.csproj]
CSC : warning AD0001: Analyzer 'Microsoft.AspNetCore.Analyzers.RouteHandlers.RouteHandlerAnalyzer' threw an exception of type 'System.IndexOutOfRangeException' with message 'Index was outside the bounds of the array.'. [C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\BankApi.Service.Stable.csproj]
CSC : warning AD0001: Analyzer 'Microsoft.AspNetCore.Analyzers.RouteHandlers.RouteHandlerAnalyzer' threw an exception of type 'System.IndexOutOfRangeException' with message 'Index was outside the bounds of the array.'. [C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\BankApi.Service.Stable.csproj]
CSC : warning AD0001: Analyzer 'Microsoft.AspNetCore.Analyzers.RouteHandlers.RouteHandlerAnalyzer' threw an exception of type 'System.IndexOutOfRangeException' with message 'Index was outside the bounds of the array.'. [C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\BankApi.Service.Stable.csproj]
CSC : warning AD0001: Analyzer 'Microsoft.AspNetCore.Analyzers.RouteHandlers.RouteHandlerAnalyzer' threw an exception of type 'System.IndexOutOfRangeException' with message 'Index was outside the bounds of the array.'. [C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\BankApi.Service.Stable.csproj]
CSC : warning AD0001: Analyzer 'Microsoft.AspNetCore.Analyzers.RouteHandlers.RouteHandlerAnalyzer' threw an exception of type 'System.IndexOutOfRangeException' with message 'Index was outside the bounds of the array.'. [C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\BankApi.Service.Stable.csproj]
  BankApi.Service.Stable -> C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\bin\Debug\net10.0\BankApi.Service.Stable.dll
  
GenerateOpenApiDocuments:
    dotnet "C:\Users\erwin\.nuget\packages\microsoft.extensions.apidescription.server\10.0.0-preview.6.25358.103\build\../tools/dotnet-getdocument.dll" --assembly "C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\bin\Debug\net10.0\BankApi.Service.Stable.dll" --file-list "obj\BankApi.Service.Stable.OpenApiFiles.cache" --framework ".NETCoreApp,Version=v10.0" --output "C:\Users\erwin\GitHub Projects\bank-api\Specs.Generated" --project "BankApi.Service.Stable" --assets-file "C:\Users\erwin\GitHub Projects\bank-api\BankApi.Service.Stable\obj\project.assets.json" --platform "AnyCPU" --file-name openapi_v1
  info: Microsoft.EntityFrameworkCore.Update[30100]
        Saved 0 entities to in-memory store.
  info: Microsoft.EntityFrameworkCore.Update[30100]
        Saved 2 entities to in-memory store.
  Generating document named 'v1'.
  Using discovered `GenerateAsync` overload with version parameter.
  Writing document named 'v1' to 'C:\Users\erwin\GitHub Projects\bank-api\Specs.Generated\openapi_v1.json'.

.NET Version

10.0.100-preview.6.25358.103

Anything else?

No response

[martincostello]

Looking at the errors, my guess would be that the source generator is failing to generate the API routes, then no routes get generated, so then there's nothing to generate into a document.

[erwinkramer]

@martincostello thanks for the suggestion but that would also mean that normal JSON spec wouldn't get created right? That just works fine.

[martincostello]

Good point, sorry missed that 😆

FWIW, for all intents and purposes the YAML-ness is like 2 lines of code in the codebase here IIRC, so it might be a problem in Microsoft.OpenApi.

[captainsafia]

@erwinkramer It seems like you are trying to generate the YAML files at build-time? At the moment, build-time document generation only supports JSON-based outputs. Support for YAML with build-time generation is tracked at #61041.

Are you seeing issues when you hit the .yaml endpoint for a running service?

[erwinkramer]

Indeed, build time. Seems like you're right, runtime just works fine, so it's a duplicate of the one you mentioned