Azure API Management OpenAPI类型Schema存储路径异常问题咨询

你的理解完全正确，这是Azure APIM的标准设计规则：

• contentType为application/vnd.oai.openapi.components+json时，Schema应该写入document/components/schemas路径，适配OpenAPI 3.x规范
• contentType为application/vnd.ms-azure-apim.swagger.definitions+json时，Schema写入document/definitions路径，适配Swagger 2.0规范

你遇到的通过REST API、Go SDK创建时不管contentType都写入definitions的问题是2020-12-01版本APIM管理API的已知问题：该版本的底层逻辑默认把所有Schema强制映射到Swagger 2.0的definitions字段下，没有按contentType区分路径，才会导致后续导出OpenAPI、开发者门户不展示的异常。

适配基于Go SDK的Terraform资源时可以用两种方法解决：

1. 将调用的APIM API版本升级到2021-08-01及以上版本，该版本已经修复了这个映射逻辑错误，会按照contentType选择正确的存储路径
2. 如果必须沿用2020-12-01版本，调用创建接口时直接传入完整的{"components":{"schemas":{你的Schema内容}}}结构，不要只传入单个Schema的定义内容，API会保留你传入的完整层级结构，不会做强制转换。

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