基于Maven的spring-cloud-contract-oa3插件处理OpenAPI契约文件异常

• 版本不兼容：你当前使用的spring-cloud-contract-oa3:2.1.2.0仅适配Spring Cloud Contract（SCC）2.x版本，和你使用的SCC 3.0.3版本插件结构、SPI加载逻辑不匹配，导致OpenApiContractConverter未被正常加载。
• 转换器优先级冲突：SCC默认的YamlContractConverter优先级更高，会先接管后缀为.yaml的文件解析，你的OpenAPI规范文件被默认转换器当作SCC原生契约格式解析，自然出现类型不匹配报错，也不会触发OA3转换器的调用。
• OpenAPI规范缺少必要扩展标识：部分版本的oa3插件需要OpenAPI文件中添加x-spring-cloud-contract相关扩展字段才会被识别为合法契约文件，否则也会跳过OA3转换器。

• 方案1：对齐兼容版本
  将SCC maven插件版本降级到2.2.x系列适配版本，示例配置如下：

<plugin>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-contract-maven-plugin</artifactId>
    <!-- 替换为和oa3 2.1.2.0适配的2.2.8.RELEASE版本 -->
    <version>2.2.8.RELEASE</version>
    <extensions>true</extensions>
    <configuration>
        <testFramework>JUNIT5</testFramework>
        <baseClassForTests>com.bt.b2c.oa3cdc.contracts.BaseTestClass</baseClassForTests>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>guru.springframework</groupId>
            <artifactId>spring-cloud-contract-oa3</artifactId>
            <version>2.1.2.0</version>
        </dependency>
    </dependencies>
</plugin>

• 方案2：排除默认YAML转换器（保留SCC 3.x版本）
  在插件配置中添加排除默认Yaml转换器的配置，让OA3转换器接管yaml文件解析：

<configuration>
    <testFramework>JUNIT5</testFramework>
    <baseClassForTests>com.bt.b2c.oa3cdc.contracts.BaseTestClass</baseClassForTests>
    <!-- 新增以下配置排除默认yaml转换器 -->
    <contractsProperties>
        <spring.cloud.contract.verifier.converter.excluded>org.springframework.cloud.contract.verifier.converter.YamlContractConverter</spring.cloud.contract.verifier.converter.excluded>
    </contractsProperties>
</configuration>

• 方案3：调整契约文件规则
  • 将OpenAPI契约文件的后缀改为.oa3.yaml，避免和原生SCC契约文件后缀冲突
  • 在OpenAPI规范的根节点添加x-spring-cloud-contract: true扩展字段，标识该文件为OA3契约文件
  • 检查OpenAPI规范语法合法性，避免存在空数组、类型不匹配的定义

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