Mule 3.9是否支持OAS 2.0及3.0？如何配置使用？

支持性结论 #

• OAS 2.0（即Swagger 2.0）：Mule Runtime 3.9原生完全支持，属于官方内置功能范畴
• OAS 3.0：无官方原生支持，仅可通过第三方适配、规范格式转换等非官方方案实现兼容，不支持OAS 3.0的全部高级特性

环境要求 #

OAS 2.0使用环境要求 #

• Mule Runtime 版本≥3.9.0，建议升级到3.9.5最新补丁版本，规避已知的Swagger解析安全漏洞
• 需预装Anypoint API Gateway 2.x组件，该组件为Mule 3.9官方安装包可选预装项
• JDK版本要求为Oracle JDK 8/OpenJDK 8，小版本号≥1.8.0_161，避免JSON解析、证书校验类异常

OAS 3.0适配环境要求 #

• Mule Runtime 版本≥3.9.4，低版本存在类加载冲突无法适配
• 需额外引入社区维护的OAS3转OAS2适配包，版本≥1.2.0，打包时内嵌到Mule应用的lib目录
• 仅支持OAS 3.0核心请求/响应定义、参数校验特性，不支持回调、多服务器配置、多内容类型复杂校验等高级特性

OAS 2.0 配置方式&使用流程 #

1. 准备符合规范的OAS 2.0文件，支持JSON/YAML格式，放置到Mule应用的src/main/resources/api目录下
2. 在应用主配置文件mule-config.xml中新增API自动发现组件配置，示例如下：

<api-platform-gw:api 
  apiName="自定义API名称" 
  apiVersion="v1" 
  flowRef="业务处理流ID" 
  doc:name="API Autodiscovery">
  <api-platform-gw:descriptor location="classpath:api/你的OAS2规范文件名.yaml" />
</api-platform-gw:api>

3. 把配置中的flowRef参数值替换为实际处理业务逻辑的流ID，完成请求路由绑定
4. 打包部署应用到Mule Runtime，启动后可通过http://<应用部署地址>:<端口>/console访问自动生成的接口调试页面，Mule会自动按照OAS 2.0的定义完成请求参数校验、Schema校验等前置逻辑

OAS 3.0 适配方案说明 #

目前生产环境可用的适配方案有两种，均为非官方方案，上线前需完成全量功能测试：

• 静态转换方案：使用swagger2openapi等工具提前将OAS 3.0规范转换为OAS 2.0格式，再按照上述OAS 2.0的配置流程操作，适配成本最低，兼容性最好
• 运行时动态转换方案：在Mule应用的入口层新增自定义Java拦截器，收到OAS 3.0格式的规范调用请求时，自动完成格式转换再交由内置OAS 2.0组件处理，适合需要动态接入多份OAS 3.0规范的场景

注意：OAS 3.0适配方案无法保证100%兼容所有OAS 3.0特性，生产环境建议优先升级到Mule 4.x版本获取原生OAS 3.0支持

内容的提问来源于stack exchange，提问作者R. Ingle