.NET Core API新增方法本地Swagger UI可见但部署后不显示的原因
部署后Swagger缺失新增接口的可能原因
- 目标环境实际运行的并非本次发布的新版本。这种是最高发的场景:构建流水线缓存了旧的编译产物、发布打包脚本没有拉取最新代码生成的dll、IIS/容器的站点物理路径指向了历史版本的程序集目录,运行的代码本身就不存在新增业务方法,Swagger自然不会展示对应接口。
- 接口文档响应被缓存。Swagger UI加载时默认请求
/swagger/v1/swagger.json获取接口列表,如果该请求的返回结果被浏览器、前置网关、CDN缓存为旧版本,就算服务端代码已经更新,前端拿到的依旧是不含新接口的旧文档。 - 新增方法所属的程序集未在目标环境被正确加载。当前给出的Swashbuckle配置没有指定额外的控制器扫描规则,默认仅扫描入口程序集中的控制器;如果本次新增方法写在类库、插件类项目中,本地调试时由于是直接项目引用,这些类库的程序集会被默认加载到应用上下文,Swashbuckle可以正常扫描,但部署后如果插件路径配置错误、类库dll没有随发布包上传,对应程序集不在ApiExplorer的扫描范围内,就会丢失这部分接口。
- 环境差异化配置拦截了新增接口的元数据采集。本地运行默认使用
Development环境,部署后多为Production环境,如果启动流程存在基于环境的判断逻辑,对非开发环境的接口集合做了过滤——比如给新增接口所在控制器配置了环境联动的[ApiExplorerSettings(IgnoreApi = true)]标记、通过动态过滤规则隐藏未在生产环境备案的接口,Swagger在生产环境生成文档时会直接跳过这部分方法。 - XML注释文件加载异常导致Swagger生成逻辑降级。当前配置中
IncludeXmlComments直接从程序基目录读取TestAPI.API.xml,如果发布流程没有将该XML文件打包到输出目录,Swashbuckle在找不到文件时会抛出异常,极端情况下如果全局异常捕获逻辑吞掉了Swagger生成流程的异常,可能出现仅生成部分旧接口文档的结果。 - 站点目录残留了旧版Swagger静态资源。如果部署前没有清空站点的wwwroot目录,残留的历史版本Swagger静态文件和当前服务端的接口版本不匹配,也会出现看不到新增接口的问题。
内容的提问来源于stack exchange,提问作者Bhav
相关产品推荐
相关产品推荐

