Support <inheritdoc /> on docs

[giggio]

It is very common to use <inheritdoc /> to extend the documentation of APIs when they use base classes, but right now NSwag does not show these docs on the generated Swagger spec.

If a class uses <inheritdoc />, all it's base classes and interface docs should be considered on the API docs, for all its methods.

If a overriding method uses <inheritdoc /> the base method docs should be considered on the API docs.

[RicoSuter]

Should :-) work: https://github.com/RSuter/NJsonSchema/blob/master/src/NJsonSchema/Infrastructure/XmlDocumentationExtensions.cs#L409

[RicoSuter]

inheritdoc is currently only checked on base classes and not interfaces

[RicoSuter]

There are tests for inheritdocs from interfaces, do you have another use case/scenario?

https://github.com/RicoSuter/Namotion.Reflection/blob/master/src/Namotion.Reflection.Tests/XmlDocsExtensionsTests.cs#L215

[stevenvolckaert]

Hi @RicoSuter! In which version should this be fixed? My projects use NSwag.MSbuild v13.10.8, and the <inheritdoc/> tags on the properties of my Web API models are not being converted into the NSwag generated code.

One of my ASP.NET Core 3.1 Web API model classes look like this:

namespace Skarabee.DocumentSigning.CoreService
{
    using System;
    using System.Collections.Generic;
    using System.ComponentModel.DataAnnotations;
    using Entities.DocumentSigningSessionAggregate;

    /// <summary>
    ///     Represents a request to create a new document signing session.
    /// </summary>
    public class CreateSessionRequest
    {
        /// <inheritdoc cref="DocumentSigningSession.ServiceInstanceName"/>
        [Required]
        public string ServiceInstanceName { get; set; }

        /// <inheritdoc cref="DocumentSigningSession.NotifySessionChangedBaseUrl"/>
        public string NotifySessionChangedBaseUrl { get; set; }

        /// <inheritdoc cref="DocumentSigningSession.Stakeholders"/>
        [Required]
        public ICollection<CreateSessionRequestStakeholder> Stakeholders { get; set; }

        /// <inheritdoc cref="DocumentSigningSession.DocumentName"/>
        [Required]
        public string DocumentName { get; set; }

        ///// <inheritdoc cref="DocumentSigningSession.DocumentGroupId"/>
        //public string DocumentGroupId { get; set; }

        /// <inheritdoc cref="DocumentSigningSession.DocumentReference"/>
        public string DocumentReference { get; set; }

        // TODO Allow specific culture names, but convert to neutral culture

        /// <inheritdoc cref="DocumentSigningSession.DocumentLanguageCode"/>
        public string DocumentLanguageCode { get; set; }

        /// <summary>
        ///     Gets or sets the document to sign, represented as a Base64-encoded string.
        /// </summary>
        [Required]
        public string DocumentAsBase64String { get; set; }

        /// <inheritdoc cref="DocumentSigningSession.ExpiresAtDateTime"/>
        public DateTime? ExpiresAtDateTime { get; set; }
    }
}

Perhaps this is fixed in v13.10.9? I wanted to upgrade to this version, which failed because my project has a dependency on Microsoft.Extensions.DependencyInjection.Abstractions v5.0.0, and NSwag.MSBuild v13.10.9 expects a dependency between v3.1.0 and v4.0.0.

Thanks in advance for your insights!

[RicoSuter]

I think this cref thing is not supported only inheritdocs without attribute reading from the base class.

[amacado]

I would appreciate an extension to support cref attribute in inheritdoc. I've found a working solution which is used in the docfx project: dotnet/docfx#1306 (comment), maybe someone could port this to nswag?

[RicoSuter]

We would need to implement/fix this in Namotion.Reflection:
https://github.com/RicoSuter/Namotion.Reflection