Azure APIM导入含外部$ref的API定义时架构对象为空

针对你导入包含外部$ref的OAS3.x API到Azure APIM后定义对象为空的问题，提供以下排查和解决方法：

• 验证外部引用的可访问性
  确认Azure APIM服务器能够访问你指定的外部YAML文件URL。可以通过curl命令或浏览器直接访问该URL，检查是否能获取到完整、无语法错误的YAML内容，且返回状态码为200 OK。如果URL处于内网环境、需要认证或被防火墙拦截，APIM将无法解析该引用。

• 合并外部Schema到主文件
  使用工具将外部引用的Schema合并到主OAS文件中，再导入APIM。例如使用swagger-cli工具执行打包命令：

  swagger-cli bundle your-main-oas.yaml -o bundled-oas.yaml
  

  打包后的文件会将所有外部$ref替换为本地定义，避免APIM解析外部引用的问题。

• 校验OAS语法正确性
  使用Swagger Editor或Redocly CLI等工具，分别校验主OAS文件和外部YAML文件的语法是否符合OAS3.x规范。例如执行Redocly的lint命令：

  redocly lint command_management_external.yaml
  

  确保外部文件中#/components/schemas/Command路径确实存在且定义正确。

• 查看APIM导入日志
  进入Azure APIM的操作详情页，或通过Azure Monitor查看APIM的导入日志，检查是否存在“无法解析外部引用”“访问被拒绝”等报错信息，这些日志能直接定位问题根源。

• 排查APIM对外部引用的限制
  尽管官方文档未明确说明，但APIM对外部$ref的支持可能存在细节限制：

  • 不支持需要身份验证的外部URL引用
  • 不支持存在重定向的外部URL
  • 仅支持公开可访问的HTTPS或HTTP地址
    如果外部URL存在上述情况，建议先将文件下载到本地，合并后再导入APIM。

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