Documentation not being generated for models from NuGet packages

[jeremyVignelles]

I have some models exposed in my APIs that come from NuGetPackages.

While those types are properly documented (I can see the doc in intellisense), they have no documentation in the generated OpenApi spec.

This does not happen on netcoreapp2.1, but does happen on netcoreapp3.1.

To highlight this issue, please see this repro:
3.1 branch :
https://github.com/jeremyVignelles/TestNSwagNetCoreApp/blob/repro/doc-external-models/TestNSwagNetCoreApp/Hello.cs#L42

2.1 branch:
https://github.com/jeremyVignelles/TestNSwagNetCoreApp/blob/repro/doc-external-models-netcoreapp2.1/TestNSwagNetCoreApp/Hello.cs#L42

I used a type from the NSwag NuGet package to highlight the issue.

[RicoSuter]

Looks like .net core 3 uses another way to reference dlls in packages so that xml docs files cannot be found.

We need to repro and fix this here:
https://github.com/RicoSuter/Namotion.Reflection

[bpaczkowski]

@RicoSuter Is there a workaround for that in the meantime? This is pretty painful for us. Too late to go back to .net core 2.x unfortunately.

[RicoSuter]

Moved to Namotion.Reflection - please repro and fix here.

[RicoSuter]

Related: #23

[jeremyVignelles]

Here is a repro for the bug using only Namotion as a NuGet package.
https://github.com/jeremyVignelles/TestNamotion

I don't know why, I didn't manage to get the XML documentation of my Program class...

[RicoSuter]

Just added a test and it seems that the XML doc file is not part of the output - only the DLL:

(there should be a NJsonSchema.xml)

[RicoSuter]

With .NET Core 2.1 the DLL is referenced in the NuGet cache where the XML is available:

[RicoSuter]

PR: #34

[RicoSuter]

Any idea how we can instruct the compiler to not only output NuGet DLLs but also the XML Docs?

/cc @pranavkm sorry to bother you again - is this possible?

[pranavkm]

I'd have thought setting <GenerateDocumentationFile>true</GenerateDocumentationFile> should suffice which your project files have set - https://github.com/RicoSuter/Namotion.Reflection/pull/34/files#diff-a0b803fa5e2b2695ee9b80fe5a60a373R5

[RicoSuter]

<GenerateDocumentationFile>true</GenerateDocumentationFile>

Only outputs the xml docs for the project itself but not for the referenced NuGet packages. So this is quite the breaking change in .net core 3.0/3.1 it seems

[pranavkm]

Ahh, are the xml files from package references no longer being copied to the output directory?

[RicoSuter]

Ahh, are the xml files from package references no longer being copied to the output directory?

It seems that this is not the case anymore... see my screenshots. The question is whether there is a csproj config where we can enable that again.

[pranavkm]

I'm not entirely sure if this was a change in the 3.x SDK. You might have much better luck asking this question of https://github.com/dotnet/core-sdk/issues.

[danielmeza]

@bpaczkowski here is a workarround RicoSuter/NSwag#2161 (comment)

[danielmeza]

Here is other solution, copy the .xml from nuget folder to the build folder
https://snede.net/add-nuget-package-xml-documentation-to-swagger/

[RicoSuter]

Ref
dotnet/sdk#1458 (comment)
dotnet/sdk#1458 (comment)

Adding this here works for me (at least in the test project):
dotnet/sdk#1458 (comment)

[RicoSuter]

v1.0.20 might be a version where this is improved but might not be fixed in all scenarios.

[RicoSuter]

Ref: dotnet/sdk#9498

https://twitter.com/RicoSuter/status/1468312527637467137

[mediawolf]

It looks to be a bug in XmlDocsExtensions.GetXmlDocsPathFromNuGetCacheFile which happens on Linux:

                var matches = Regex.Matches(json, $"\"((.*?){assemblyName.Name}((\\\\\\\\)|(////)){assemblyName.Version.ToString(3)})((\\\\\\\\)|(////))(.*?)\"", RegexOptions.IgnoreCase);

It should be a single forward slash - not four because no escaping is needed. Same could be applicable to runtimeConfigRegex
declared in the same file.