OpenAPI XML docs: Improvements to XML comment generator

[Rick-Anderson]

Description

See #35217 (comment)

The following information needs to be addressed for the Page URL within its Content Source URL below, but with the perspective how the feature currently works in .NET 10 as opposed to what has changed with .NET 10 since the context of the document to be updated is already .NET 10.

Improvements to the XML comment generator

XML comment generation handles complex types in .NET 10 better than earlier versions of .NET.

• It produces accurate and complete XML comments for a wider range of types.
• It handles more complex scenarios.
• It gracefully bypasses processing for complex types that cause build errors in earlier versions.

These improvements change the failure mode for certain scenarios from build errors to missing metadata.

In addition, XML doc comment processing can now be configured to access XML comments in other assemblies. This is useful for generating documentation for types that are defined outside the current assembly, such as the ProblemDetails type in the Microsoft.AspNetCore.Http namespace.

This configuration is done with directives in the project build file. The following example shows how to configure the XML comment generator to access XML comments for types in the Microsoft.AspNetCore.Http assembly, which includes the ProblemDetails class.

<Target Name="AddOpenApiDependencies" AfterTargets="ResolveReferences">
  <ItemGroup>
  <!-- Include XML documentation from Microsoft.AspNetCore.Http.Abstractions
    to get metadata for ProblemDetails -->
    <AdditionalFiles
          Include="@(ReferencePath->'
            %(RootDir)%(Directory)%(Filename).xml')"
          Condition="'%(ReferencePath.Filename)' ==
           'Microsoft.AspNetCore.Http.Abstractions'"
          KeepMetadata="Identity;HintPath" />
  </ItemGroup>
</Target>

We expect to include XML comments from a selected set of assemblies in the shared framework in future previews to avoid the need for this configuration in most cases.

Unified handling of documentation IDs in OpenAPI XML comment generator

XML documentation comments from referenced assemblies are correctly merged even when their documentation IDs include return type suffixes. As a result, all valid XML comments are reliably included in generated OpenAPI documentation, improving documentation accuracy and completeness for APIs using referenced assemblies.

Page URL

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

Content source URL

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

Document ID

7d97465d-3ebd-98f5-4129-71d213954b1f

Platform Id

c962d7fd-2c50-2e76-d0e8-ecf50c45bc3c

Article author

@captainsafia

Metadata

• ID: 7d97465d-3ebd-98f5-4129-71d213954b1f
• PlatformId: c962d7fd-2c50-2e76-d0e8-ecf50c45bc3c
• Service: aspnet-core
• Sub-service: fundamentals

Related Issues

---

Associated WorkItem - 449127