Developer
Keep the generator on and filter only what collides
/openapi/v1.json answers 500 with "An item with the same key has already been added" because a type your API documents is also documented in more than one referenced project, and the only workaround you have found turns the XML-comment generator off.
<!-- the project that calls AddOpenApi() -->
<PackageReference Include="Purview.OpenAPI.XmlComments" Version="1.0.0" PrivateAssets="all" />
What you get: Every colliding documentation ID is removed from the referenced documentation before compile, the generator runs on the filtered copies, and the description of every other endpoint and schema stays in the document.
Every occurrence of a colliding ID goes, not all but the first, because the API usually declares the injected type as well: keeping a reference's copy would still collide with it. A duplicated ID is ambient code rather than API surface, and a copy is only rewritten when its content changes, so a no-change build still skips CoreCompile.
Read the guide →
Developer
List every colliding ID rather than the first one
The exception names one documentation ID, and the build says nothing about the rest, so you do not know whether one exclude is enough or whether the generator fails again on the next build.
pwsh skills/purview-openapi-xmlcomments-duplicates/scripts/find-duplicate-documentation-ids.ps1 `
-Project path/to/Api
What you get: The script asks MSBuild for exactly the documentation files the generator reads and reports every colliding ID, where each copy comes from, whether the current configuration already handles it, and the item to add when it does not.
Each finding is classified: BetweenReferences is handled automatically by the package, while ReferenceAndProject needs the PurviewOpenAPIXmlCommentExclude item the script prints. It exits 0 when nothing would throw, 1 when something would, and 2 when it could not inspect the project.
Read the guide →
Team lead
Fail the build on a collision instead of a 500 in production
The overlap is only visible after the API compiles, so a warning is easy to ship, and the failure then surfaces as a 500 on the OpenAPI document rather than as a red build.
<PropertyGroup>
<!-- fail the build instead of leaving the collision to run time -->
<MSBuildWarningsAsErrors>$(MSBuildWarningsAsErrors);POAX001</MSBuildWarningsAsErrors>
</PropertyGroup>
What you get: POAX001 fails the build and names the exact PurviewOpenAPIXmlCommentExclude item to add, so an unhandled collision is a pull-request failure instead of a runtime error.
The check runs after CoreCompile and compares the API's fresh documentation file with the filtered reference documentation, which is the one case the before-compile pass cannot see: an ID documented in the API and in exactly one referenced project.
Read the guide →
Architect
One repository-wide reference that costs nothing at run time
Several API projects in the same repository reference the same generators, and you do not want per-project wiring or a build fix that becomes a runtime dependency.
<!-- Directory.Packages.props: once for every project in the repository -->
<GlobalPackageReference Include="Purview.OpenAPI.XmlComments" Version="1.0.0" />
What you get: One declaration covers every project and does nothing in a project that does not reference Microsoft.AspNetCore.OpenApi, so libraries in the same repository need no exemption.
The package ships only props, targets and a netstandard2.0 task assembly under tasks/; lib/, ref/ and runtimes/ are forbidden by pack validation, so it adds no runtime dependency and copies nothing into the consumer's build output.
Read the guide →
