OpenApiGenerateDocumentsOnBuild instead of OpenApiGenerateDocuments

[ronaldkroon]

Description

It seems that the property to generate the Open API document should be OpenApiGenerateDocumentsOnBuild instead of OpenApiGenerateDocuments. For me the generation started working after changing this property name.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview?view=aspnetcore-9.0

Content source URL

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

Document ID

d8ac1ac3-8b34-6886-bca4-740514f94229

Platform Id

fc9e39cd-d174-e15e-47f9-bedd1b2be2cd

Article author

@Rick-Anderson

Metadata

• ID: d8ac1ac3-8b34-6886-bca4-740514f94229
• PlatformId: fc9e39cd-d174-e15e-47f9-bedd1b2be2cd
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues

[Rick-Anderson]

@martincostello I'm going to change this from Document generation at ~build~ run time is enabled by setting the OpenApiGenerateDocuments property.

Then I'll add:

Document generation at build time is enabled by setting the OpenApiGenerateDocumentsOnBuild property.

 <PropertyGroup>
    <OpenApiGenerateDocumentsOnBuild>true</OpenApiGenerateDocumentsOnBuild>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

[nlykkei]

@Rick-Anderson What do you mean by

Document generation at build run time is enabled by setting the OpenApiGenerateDocuments property.

?

Isn't document generation at runtime controlled by the Swagger package?

In the code, it says that OpenApiGenerateDocumentsOnBuild is set to true, if OpenApiGenerateDocuments is set to true, but that's not the case. If I set OpenApiGenerateDocuments to true, then generation doesn't happen at build time

[martincostello]

IIRC the bug is that the property is misnamed in the documentation:

- OpenApiGenerateDocuments
+ OpenApiGenerateDocumentsOnBuild

The former doesn't generate anything because that's not the right name.

Tools, such as Swashbuckle, are only invoked when the MSBuild property to instruct the targets to do so is set to true.