Swagger
Swagger 这一页别想复杂。
对大多数项目来说，它主要解决两件事：
- 生成接口文档
- 提供一个可以直接调接口的页面
它不负责替你补接口注释，也不负责自动生成项目 XML 文件。
所以想让 Swagger 正常工作，至少要有三样东西：
Component.deps.jsonSwagger配置节- 项目 XML 注释输出
最小接入方式
1. 在 Component.deps.json 中启用 Swagger
{
"Components": {
"Services": [
"Swagger"
],
"Middlewares": [
"Swagger"
]
}
}
2. 在配置文件里加上 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}"
}
}
}
3. 开启项目 XML 注释输出
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
4. 启动后打开 /swagger/index.html
页面能打开、接口能看到、需要认证时也有按钮，基本就说明通了。
两个最常见的场景
只给当前启动项目生成文档
{
"Swagger": {
"IsEnabled": true,
"Title": "My API",
"Version": "v1",
"XmlCommentsPath": "{CurrentDirectory}/{CurrentProject}.xml"
}
}
适合：
- 控制器、请求对象、返回对象都主要在当前项目里
- 先把 Swagger 页面跑起来
同时合并 DTO 或共享类库注释
{
"Swagger": {
"IsEnabled": true,
"Title": "My API",
"Version": "v1",
"XmlCommentsPath": "{CurrentDirectory}/{CurrentProject}.xml",
"ExtensionXmlComments": [
"{CurrentDirectory}/*.Dto.xml",
"{CurrentDirectory}/Aegis.Transfer.xml"
]
}
}
适合：
- DTO 不在启动项目里
- 公共返回对象或枚举定义在独立类库里
需要认证时怎么调
如果接口需要认证，建议把安全头定义一并打开。
{
"Swagger": {
"SecurityScheme": {
"SecurityEnabled": true,
"AddBearerHeader": true,
"BearerName": "Authorization",
"Description": "Value Bearer {token}"
}
}
}
通常就是这几步：
- 先通过登录接口拿到 token
- 点击 Swagger UI 里的认证按钮
- 按页面说明填写值
- 再调用受保护接口
什么时候再补 ExtensionXmlComments
遇到下面这些情况，再补它最合适：
- 页面里只有控制器说明，没有字段说明
- 模型显示出来了，但枚举注释缺失
- DTO 和 Contract 不在启动项目
常见问题
为什么已经启用组件，但浏览器里没有 Swagger 页面
先查这几项：
Services是否包含SwaggerMiddlewares是否包含SwaggerSwagger:IsEnabled是否为true
为什么启动时报 XML 文件不存在
通常是这几个原因：
- 项目没有开启 XML 输出
- 路径写错
- 发布时 XML 没有进入运行目录
为什么 Swagger 页面有接口，但没有注释
大多数情况下就是 XML 文件没有正确生成或加载。
如果主项目有注释、DTO 没注释，通常再补 ExtensionXmlComments 就能解决。
为什么 Swagger 里没有认证按钮
先检查 SecurityScheme.SecurityEnabled 是否开启。
再检查 BearerName 是否和你们实际使用的请求头名称一致。