Integrate .NET 10 XML comment improvements into OpenAPI documentation seamlessly (#35996)

* Initial plan

* Add .NET 10 XML comment generator improvements to OpenAPI docs

Co-authored-by: wadepickett <[email protected]>

* Update ms.date metadata to 08/25/2025 as requested

Co-authored-by: wadepickett <[email protected]>

* Reintegrate .NET 10 improvements seamlessly into existing sections

Co-authored-by: wadepickett <[email protected]>

* Update aspnetcore/fundamentals/openapi/openapi-comments.md

Removed comment about back up author

* Remove code comments from XML configuration example as they are not localized

Co-authored-by: wadepickett <[email protected]>

* Enhance OpenAPI comments with .NET 10 improvements

Revert to .NET 10 specific summary

* Update aspnetcore/fundamentals/openapi/openapi-comments.md

* Update aspnetcore/fundamentals/openapi/openapi-comments.md

removed extra line

* Update aspnetcore/fundamentals/openapi/openapi-comments.md

Edit and clean up for XML comment gen paragraph.

* Update aspnetcore/fundamentals/openapi/openapi-comments.md

Co-authored-by: Mike Kistler <[email protected]>

* Apply suggestions from code review

Added great suggestions from Mike.

Co-authored-by: Mike Kistler <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: wadepickett <[email protected]>
Co-authored-by: Wade Pickett <[email protected]>
Co-authored-by: Mike Kistler <[email protected]>

Author: 3 people

aspnetcore/fundamentals/openapi/openapi-comments.md

@@ -1,14 +1,14 @@
 ---
 title: ASP.NET Core OpenAPI XML documentation comment support in ASP.NET Core
+ai-usage: ai-assisted
 author: captainsafia
 description: Learn how to integrate XML documentation comments on types by OpenAPI document generation in ASP.NET Core.
-ms.author: safia
 monikerRange: '>= aspnetcore-10.0'
+ms.author: safia
 ms.custom: mvc
-ms.date: 04/15/2025
+ms.date: 08/25/2025
 uid: fundamentals/openapi/aspnet-openapi-xml
 ---
-<!-- backup author: rick-anderson -->
 # OpenAPI XML documentation comment support in ASP.NET Core
 
 ASP.NET Core XML documentation processing extracts code comments automatically to populate API documentation, ensuring the code and documentation remain synchronized. Metadata from XML documentation comments is included in the generated OpenAPI document without requiring changes to the app code, as long as the project is configured to generate the XML documentation file. XML documentation comments are automatically detected in the application assembly and referenced assemblies with XML documentation enabled.
@@ -106,6 +106,21 @@ To include XML documentation files from referenced assemblies, add them as `Addi
 </ItemGroup>
 ```
 
+XML doc comment processing can 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:
+
+```xml
+<Target Name="AddOpenApiDependencies" AfterTargets="ResolveReferences">
+  <ItemGroup>
+    <AdditionalFiles
+          Include="@(ReferencePath->'
+            %(RootDir)%(Directory)%(Filename).xml')"
+          Condition="'%(ReferencePath.Filename)' ==
+           'Microsoft.AspNetCore.Http.Abstractions'"
+          KeepMetadata="Identity;HintPath" />
+  </ItemGroup>
+</Target>
+```
+
 #### Disabling XML documentation support
 
 To turn off XML documentation integration, remove the source generator from the `Analyzers` item group. Removing the source generator prevents it from being used during compilation.
@@ -130,6 +145,14 @@ XML comments are parsed into structured `XmlComment` objects with:
 * Response documentation with status codes and descriptions.
 * Support for examples and deprecated markers.
 
+### Handling of complex types
+
+XML comment processing produces accurate and complete OpenApi descriptions for a wide range of types and supports complex scenarios. But if an error is encountered when processing a complex types, the process bypasses the type gracefully.
+
+In this way, scenarios that might have resulted in build errors now simply result in missing metadata, helping to avoid build failures.
+
+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.
+
 ### `<inheritdoc/>`
 
 The generator supports [`<inheritdoc>`](/dotnet/csharp/language-reference/xmldoc/recommended-tags#inheritdoc) tags, which inherit documentation *as long as they exist in the compilation assembly*. `<inheritdoc />` tags indicate that comments must be resolved from: