如何以最简方式为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”选项。

内容的提问来源于stack exchange,提问作者Charles Burns
相关产品推荐
相关产品推荐

