You need to enable JavaScript to run this app.
优惠活动
大模型
产品
解决方案
定价
更多

如何以最简方式为Swagger添加XML文档?

如何简化.NET中Swagger集成XML文档的操作?

我在所有Web API项目中都使用Swagger,希望将源代码文档集成到其中——毕竟文档功能是Swagger的核心价值之一。写下这些内容,是为了给自己和社区提供实用参考。

之前用过的几种复杂实现方式

依赖已弃用的旧版代码

我之前长期使用网上示例中的这段代码,但其中Microsoft.Extensions.PlatformAbstractions已被弃用,GetTypeInfo还需要额外引用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";
var xmlDocsPath = Path.Combine(AppContext.BaseDirectory, xmlFileName); // 没法合并成一行,略显啰嗦
builder.Services.AddSwaggerGen(options => { options.IncludeXmlComments(xmlDocsPath); });

我的疑问

以我的使用经验,现代.NET相比PHP、Python、Java及C++简化了绝大多数编程任务,但Swagger集成XML文档这种常见操作却显得格外复杂。想请教:是否存在更简单的实现方法?最好不需要硬编码程序名,也不用借助反射?


给后续读者的提示

XML文档不会默认生成,需要自行在项目或IDE中启用该功能:

  • 对于Jetbrains Rider:打开项目属性,在Debug和/或Release配置下勾选“Generate”选项。
    Rider中启用XML文档生成的界面

内容的提问来源于stack exchange,提问作者Charles Burns

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.07.03 09:05:32