如何将Stoplight OpenAPI 3.1转换为3.0解决Azure兼容性问题

我去年对接Azure API Management做接口导入的时候踩过完全相同的坑，Stoplight默认导出的OpenAPI 3.1版本Azure侧全版本不识别，前前后后试了四五种方案，最终跑通的可行方案按可靠性排序如下：

• 方案1：Stoplight原生导出（最适配你当前的编辑场景，零额外工具成本）
  不用找第三方转换工具，Stoplight本身就支持导出3.0版本规范：打开目标API项目，点击右上角导出按钮，下拉选择OpenAPI 3.0 (JSON/YAML)即可导出。
  必须提前处理的兼容坑点，不然导出会丢字段或者生成不符合3.0规范的内容：

  • 删掉所有用const关键字定义的固定值，3.0版本不支持该关键字，替换成enum且数组内仅保留那一个固定值即可
  • 替换所有JSON Schema 2020-12独有的语法，比如prefixItems改成普通数组items定义，$dynamicRef/$dynamicAnchor全部替换为普通$ref引用
  • 把所有type: ['null', 实际类型]的数组式联合类型写法，改成3.0兼容格式：比如可空字符串就写type: string + nullable: true，不要用数组声明多类型

• 方案2：本地命令行批量转换（适合大体积规范、多文件批量处理场景）
  不建议用不知名在线转换工具，容易泄露接口敏感信息、漏转字段，用本地开源工具转换更可控：

  1. 提前安装Node.js环境，全局安装转换工具：执行命令npm install -g api-spec-converter
  2. 执行转换：api-spec-converter --from=openapi_3 --to=openapi_3 --syntax=yaml 你的3.1版本规范文件.yaml > 转换后3.0版本规范.yaml
  3. 转完强制做规范校验：全局安装校验工具npm install -g @redocly/cli，执行redocly lint 转换后3.0版本规范.yaml --extends=minimal，把所有报出的3.0版本不兼容错误手动修复即可
     踩过的实坑：这个工具不会自动处理nullable联合类型、const字段的转换，必须过一遍校验，不然导入Azure时会报无明确指向的schema解析错误。

• 导入Azure前的必做检查

  不要转完就直接往Azure APIM或者其他Azure服务里导，先做两个必查项，能避开90%的导入报错：

  1. 确认规范顶层的版本号字段是openapi: 3.0.3，很多转换工具不会自动修改这个顶层字段，Azure只要识别到3.1.x的版本号就会直接走3.1解析逻辑报错
  2. 删掉安全定义中3.1独有的配置，比如OAuth2授权码流里的顶层pkce: true字段，3.0版本不支持该配置，需要的话可以放到x-开头的扩展字段里

我当时最开始图省事用在线工具转，转完导入Azure一半接口报参数校验错误，排查了俩小时，后来换回Stoplight原生导出，手动改了3处const定义和可空类型写法，5分钟就搞定，一次导入通过。

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