能否在 ApiMember 属性和 xmldoc 摘要注释中使用相同的描述？

Question

在我的 API 模型组件中，我大量使用 ApiMember 属性来为 Swagger UI 的属性提供描述，例如

public class FindVendorItems : IReturn<List<VendorItem>>, IGet
{
    [ApiMember(Descripton = Description.ItemId)]
    public int ItemId { get; set; }
}

描述是静态 Description class 中的常量字符串，因此它们可以在整个模型中使用以保持描述的一致性。

这对 Swagger 非常有效，但我想解决的问题是将相同的描述添加到 XML 文档注释的摘要标签中，以便它们在 Visual Studio 中可用和可见.我不想 copy/paste 从常量到摘要标签的描述，因为它被证明容易出错并且两者很快就会失去同步。

public class FindVendorItems : IReturn<List<VendorItem>>, IGet
{
    /// <summary>
    /// Same Description.ItemId here
    /// </summary>
    [ApiMember(Descripton = Description.ItemId)]
    public int ItemId { get; set; }
}

有什么方法可以自动执行此操作吗？即使它在 Visual Studio 中不可见，只要构建生成的结果 XML 文件包含所有描述，这样就可以在使用由此构建的 NuGet 包时提供 IntelliSense。

Answer 1

这是不可能的，因为执行 .NET 代码无法访问包含开发工具和 IDE 可以访问的 XML API 文档的外部 .xml 文件。

ServiceStack 支持 dynamically adding attributes 因此有可能使用一些外部代码生成工具来解析 XML 文档文件并生成 C# 代码以在启动时将文档属性动态添加到您的 DTO 类型.

Answer 2

我想出了一个解决方案。我对模型中的所有类型和成员（请求和响应 DTO）使用了 XML 文档注释，然后编写了一个自定义 ApiDeclarationFilter 来解析 XML 文档文件并替换描述和Open API 响应中的摘要属性与 XML 文档中的属性。

为了 re-use 跨类型和成员的描述，我将 XML 文档放在一个单独的 XML 文件中，并使用以下方法引用相应的成员：

/// <include file='../XmlDocs.xml' path='members/member[@name="MyPropertyName"]/*' />

能否在 ApiMember 属性和 xmldoc 摘要注释中使用相同的描述？

Can you use the same description in the ApiMember attribute and xmldoc summary comment?

c#

servicestack