Swagger 文档扩展（Aegis.Extensions.Swagger）
Aegis.Extensions.Swagger 用来给 Web API 提供 OpenAPI 文档、Swagger UI 调试入口和认证头说明。它不是单纯的服务注册组件，而是同时覆盖了服务注册和中间件接入，所以接入时要把 Swagger 同时放进 Services 和 Middlewares。
组件概览
| 字段 | 说明 |
|---|---|
| 组件名称 | Swagger 文档扩展 |
| 真实类库 | Aegis.Extensions.Swagger |
| 组件定位 | OpenAPI 文档生成与 Swagger UI 入口 |
| 引入方式 | 安装 NuGet，并在 Component.deps.json 中启用 Swagger |
| 组件声明 | Swagger |
| 配置节点 | Swagger |
| 核心能力 | 生成接口文档、挂载 Swagger UI、显示认证请求头、合并扩展 XML 注释 |
什么时候要用它
适合场景：
- 需要给前后端联调提供在线接口文档
- 需要给测试或实施人员提供 Swagger UI 调试入口
- 需要把接口 XML 注释同步展示到文档页里
- 需要在 Swagger UI 里直接填写
Authorization等安全头
最小可运行路径
第一步：启用 Swagger
这个组件既要注册 AddSwaggerGen(...)，也要把 UseSwagger() 和 UseSwaggerUI() 放进请求管线，所以两处都要配置。
{
"Components": {
"Services": [
"Swagger"
],
"Middlewares": [
"Swagger"
]
}
}
第二步：准备 Swagger 配置
{
"Swagger": {
"IsEnabled": true,
"Title": "Aegis Demo",
"Version": "v1",
"XmlCommentsPath": "{CurrentDirectory}/{CurrentProject}.xml",
"ExtensionXmlComments": [
"{CurrentDirectory}/*.Dto.xml"
],
"SecurityScheme": {
"SecurityEnabled": true,
"AddBearerHeader": true,
"BearerName": "Authorization",
"Description": "Value Bearer {token}"
}
}
}
第三步：确保项目生成 XML 注释文件
如果没有 XML 注释文件，Swagger 页面可以挂出来，但注释说明和很多模型描述都会缺失；当 XmlCommentsPath 指向了不存在的文件时，应用启动还会直接报错。
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
第四步：启动后访问 Swagger UI
通常访问：
/swagger/swagger/index.html
如果项目启用了虚拟目录或网关前缀，再按实际发布路径访问。
这组配置分别控制什么
| 配置项 | 作用 |
|---|---|
IsEnabled | 是否启用 Swagger |
Title | 文档标题 |
Version | Swagger 文档版本号 |
XmlCommentsPath | 当前主项目 XML 注释文件路径 |
ExtensionXmlComments | 额外 XML 注释文件列表，常用于合并 DTO 或其他类库注释 |
SecurityScheme.SecurityEnabled | 是否启用安全头定义 |
SecurityScheme.AddBearerHeader | 是否按 Bearer 口径展示认证头 |
SecurityScheme.BearerName | 认证请求头名称，通常保持 Authorization |
SecurityScheme.Description | Swagger UI 中显示的认证头说明 |
配置时最容易忽略的两个占位符
{CurrentDirectory}
表示当前程序运行目录。
最常见用途是把 XML 路径写成：
{
"Swagger": {
"XmlCommentsPath": "{CurrentDirectory}/{CurrentProject}.xml"
}
}
{CurrentProject}
表示当前启动项目名称。
如果 XML 文件名和启动项目同名，这个占位符能避免每个项目都手动改一遍。
如何把 DTO、扩展类库的注释也带进 Swagger
当接口返回类型、请求对象、枚举说明分散在多个类库时，只写主项目 XML 往往不够。
这时候可以把附加 XML 放进 ExtensionXmlComments。
{
"Swagger": {
"XmlCommentsPath": "{CurrentDirectory}/{CurrentProject}.xml",
"ExtensionXmlComments": [
"{CurrentDirectory}/*.Dto.xml",
"{CurrentDirectory}/Aegis.Transfer.xml"
]
}
}
如果你的 XML 文件命名有统一规律，可以直接使用通配符。
什么时候要开启安全头说明
只要接口需要登录态、JWT、SSO 或其他令牌头，通常都建议打开 SecurityScheme。
{
"Swagger": {
"SecurityScheme": {
"SecurityEnabled": true,
"AddBearerHeader": true,
"BearerName": "Authorization",
"Description": "Value Bearer {token}"
}
}
}
启用后，Swagger UI 会出现认证按钮，方便联调时直接填写头信息。
推荐的接入顺序
- 先完成控制器、认证、DTO 注释
- 再启用
Swagger - 然后补主项目 XML 输出
- 最后再按需要合并 DTO 或共享类库 XML
这样排查问题时最简单，能先确认 Swagger 本身是否起来，再逐步补细节。
接入完成后怎么确认成功
你至少应该确认这些点：
Component.deps.json的Services和Middlewares都包含了SwaggerSwagger:IsEnabled为trueXmlCommentsPath指向的 XML 文件真实存在/swagger/index.html可以正常打开- 页面里能看到控制器、动作说明和模型字段注释
- 如果启用了认证，页面右上角能看到认证按钮
常见问题
为什么项目启动后没有 Swagger 页面
优先检查：
Services是否包含SwaggerMiddlewares是否包含SwaggerSwagger:IsEnabled是否为true
只配了 Services 没配 Middlewares，通常表现就是服务注册成功了，但浏览器端没有 Swagger UI。
为什么启动时报 XML 文件找不到
最常见原因是：
- 项目没有开启 XML 文档输出
XmlCommentsPath写错了- 发布目录里没有把 XML 一起带上
优先先看运行目录里是否真的有目标 XML 文件。
为什么页面能打开，但没有接口说明和模型说明
这通常是 XML 文件没生成，或者只挂了主项目 XML，没有把 DTO 所在类库 XML 一起引入。
为什么页面里没有认证按钮
优先检查 SecurityScheme.SecurityEnabled 是否为 true。
如果已经开启，再确认 BearerName 和你们实际使用的请求头名称是否一致。