Fastify配置OpenAPI 3.0.0时swagger无法加载的调试方法咨询

1. 校验生成的OpenAPI规范合法性 #

你删除部分schema即可正常运行，首先排查生成的规范文件不符合OpenAPI 3.0标准的问题：

• 直接访问插件生成的原始规范地址：在你配置的routePrefix路径后加.json后缀，例如你的配置是${constants.EXTERNAL_PATH}/api-docs，就访问${constants.EXTERNAL_PATH}/api-docs/json或者${constants.EXTERNAL_PATH}/api-docs/swagger.json拿到完整的OpenAPI JSON内容
• 使用本地校验工具验证JSON合法性，可安装openapi-schema-validator工具执行校验，快速定位字段错误、格式错误的位置

2. 开启调试日志抓取内部报错 #

默认日志级别不会输出插件内部的schema解析错误，开启debug日志即可看到隐藏的报错：

• 初始化Fastify实例时开启debug级别的日志：

const fastify = require('fastify')({ 
  logger: { level: 'debug' } 
})

• 注册fastify-oas时也指定logLevel为debug，确保所有插件内部日志都能输出：

fastify.register(require('fastify-oas'), { ...swaggerConfig, logLevel: 'debug' });

3. 二分法定位问题schema #

用最小成本定位出问题的具体路由/字段：

• 先注释掉一半的路由schema配置，测试swagger是否能正常加载
• 如果正常就排查被注释的一半，不正常就排查当前保留的一半，重复操作3-5次就能定位到具体有问题的schema配置
• 重点检查不兼容的字段：你当前用的securityDefinitions、schemes都是OpenAPI 2.0的配置字段，OpenAPI 3.0中对应的配置是components.securitySchemes、servers字段，旧字段不兼容会直接导致生成的规范文件失效

4. 检查依赖版本兼容性 #

确认fastify和fastify-oas的版本匹配：

• fastify 3.x对应fastify-oas 2.x版本
• fastify 4.x对应fastify-oas 3.x及以上版本
• 版本不匹配时可重新安装兼容版本验证：npm i fastify-oas@3.x fastify@4.x

内容的提问来源于stack exchange，提问作者Pradip