向 Swagger 添加 XML 文档的最简单方法是什么？

Question

这个问答问题旨在为我自己以及希望为社区提供有用的参考。我将 Swagger 用于所有 Web API，并喜欢它包含我的源代码文档，因为 Swagger 主要是关于文档。

我长期以来一直使用一些在线示例中的以下内容，但是

Microsoft.Extensions.PlatformAbstractions

现已弃用，

GetTypeInfo

需要

using System.Reflection;

，并且仅获取 XML 文件的路径的代码总体上很复杂：

using Microsoft.Extensions.PlatformAbstractions;
using System.Reflection;
// ...
builder.Services.AddSwaggerGen(options => {
    var basePath = PlatformServices.Default.Application.ApplicationBasePath;
    var fileName = typeof(Program).GetTypeInfo().Assembly.GetName().Name + ".xml";
    var xmlPath = Path.Combine(basePath, fileName);
    options.IncludeXmlComments(xmlPath);
});

后来进行了一个小的可读性改进，但需要

Microsoft.DotNet.PlatformAbstractions

，已被删除。

    ...
    var basePath = ApplicationEnvironment.ApplicationBasePath;
    ...

我简单地使用了这个稍短的代码，但它仍然需要显式引用

System.Reflection

：

using System.Reflection;
// ...
var xmlFileName = Assembly.GetExecutingAssembly().GetName().Name + ".xml";
Path.Combine(AppContext.BaseDirectory, xmlFileName); // A bit too long to combine into 1 line
builder.Services.AddSwaggerGen(options => { options.IncludeXmlComments(xmlDocsPath); });

根据我的经验，现代 .NET 使大多数编程任务比我使用过的其他语言（PHP、Python、Java 和 C++）更简单，但就我认为的普遍程度而言，这似乎有点复杂。

是否有更简单的方法将 XML 文档添加到 Swagger，最好不要对程序名称进行硬编码或使用任何反射？

---

对于未来的读者：默认情况下不会生成 XML 文件。在线搜索如何在您的项目中或使用 IDE 启用它。 对于 Jetbrains Rider：打开项目属性并选中“调试”和/或“发布”下的“生成”框。

Answer 1

我最近决定了以下事项。

Assembly.GetName()

看起来非常反射，尽管代码不再需要显式引用

System.Reflection

但这很好，因为这总体上相当简单和简短，并且对我有用：

var xmlDocsPath = Path.Combine(AppContext.BaseDirectory, typeof(Program).Assembly.GetName().Name + ".xml");
builder.Services.AddSwaggerGen(options => { options.IncludeXmlComments(xmlDocsPath); });

将

Program

替换为您的启动类（如果名称不同）。

收集程序名称是因为大多数 IDE 中的默认 XML 文件名是

{ProgramName}.xml

，但您可以轻松地将其作为设置过程的一部分来显式命名文件，并使用该名称代替

Assembly.GetName...

.