XML documentation on controllers/endpoints from referenced class libraries is not manifested in OpenAPI document

[ZTonks]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

XML documentation is not parsed into OpenAPI documents from endpoints which come from dependent libraries. This means the feature does not support APIs built from multiple modules well.

This should be supported given the endpoint definitions themselves from the class libraries are parsed into the document, just without their supporting XML documentation.

As an example one pattern might be that controllers are defined in separate libraries for easier separation of concerns, but deployed as one unit as one API executable (modular monolith).

Expected Behavior

XML documentation for any endpoint which is added to the generated OpenAPI document accompanies the endpoint docs whenever the endpoint is added to the document

Steps To Reproduce

https://github.com/ZTonks/XML_NET_OpenAPI_MWE

Run API project from Visual Studio (such that Scalar is opened via launchSettings) (this is the easiest way of seeing the results of the OpenAPI document)

Exceptions (if any)

XML documentation is added to the endpoints which are from consumed libraries

.NET Version

10.0.100

Anything else?

Visual Studio 2026 18.0.1

Host:
Version: 10.0.0
Architecture: x64

<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.2.25161.17" />

Other RC versions of the package I tried also exhibit this behaviour

[MihuBot]

I'm a bot. Here are possible related and/or duplicate issues (I may be wrong):

• Support XML-based OpenAPI docs for minimal and controller-based APIs with Microsoft.AspNetCore.OpenApi #39927
• [XmlCommentGenerator] AddOpenApi cannot recognize the entry assembly #62941

[martincostello]

This is essentially the same ask as #63225 and #64439.

[desjoerd]

You need to include xml documentation files of dependent nuget files. An example is given here:

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

Please see if this works 🙂.

[ZTonks]

You need to include xml documentation files of dependent nuget files. An example is given here:

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

Please see if this works 🙂.

I am aware of these options but these are class libraries not NuGet packages. In any case, the docs don't actually sufficiently describe how to get at those files when the dependent XML files are generated at build time. Or in other words if I follow the docs to the letter for directly referenced assemblies then it doesn't work, it would say that file does not exist.

What it seems like would actually be required would be referencing each XML file in the bin folder of each built assembly. Which while possible is not the most obvious solution.

[ZTonks]

In terms of importing them from the build outputs, this works in the MWE:

<AdditionalFiles Include="../LibraryWithControllers/$(OutputPath)LibraryWithControllers.xml" />

i.e. use the file from the build (it will not naturally exist)

However, if I apply this solution in the actual code I am trying to build with, rather than the example solution, I get errors such as

An item with the same key has already been added. Key: [the fully qualified name of a type]

i.e. elements of the imported XML file are conflicting with keys resolved at runtime for the main exe (because there is a dependency on the class library from the exe).

This looks to be a similar issue as #64378 in a different context.

I am struggling to reproduce this in the MWE repo linked already, or at least it would take some time to reconstruct a similar case to the actual code I am working with.

What I would suggest is that the import of XML files isn't playing nicely with the XML comments actually resolved at runtime and it's not sufficient to concatenate them them in.

So in total:

1. I am not sure the docs are correct to describe how to import XML files which are generated at build time
2. This feature seems to be a bit brittle in terms of the way the XML files are manually brought in and then combined with comments at runtime...i.e. it's a mixed approach.

[martincostello]

However, if I apply this solution in the actual code I am trying to build with, rather than the example solution, I get errors such as

An item with the same key has already been added. Key: [the fully qualified name of a type]

This might be #64378.

[desjoerd]

@ZTonks as you have packages with Controllers maybe you also have access to the IServiceCollection or some bootstrapper code. You could add AddOpenApi in the nuget packages containing the controllers. AddOpenApi can be called multiple times. This will add the interceptor which adds the xml documentation transformers.