如何仅在内部OpenAPI YAML模型保留x-implements，交付客户时移除？

解决方案：无需手动修改或维护双份Schema的自动化处理方案 #

你需要在保留内部开发所需的x-implements扩展字段的同时，自动生成无该字段的OpenAPI文件用于客户交付，以下是几个高效可行的方案：

方案1：利用OpenAPI Generator内置配置过滤扩展字段

maven-openapi-generator支持通过配置参数移除特定的扩展属性。如果目标是生成供客户使用的标准化OpenAPI文件，可使用removeSchemaExtension参数指定要清理的字段：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>最新稳定版本</version>
    <executions>
        <execution>
            <id>generate-client-openapi</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
                <generatorName>openapi-yaml</generatorName> <!-- 输出标准化YAML格式 -->
                <output>${project.build.directory}/client-openapi</output>
                <configOptions>
                    <removeSchemaExtension>x-implements</removeSchemaExtension> <!-- 自动移除所有Schema的x-implements字段 -->
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

执行该插件后，会自动生成清理后的OpenAPI文件，原文件无需任何修改。

方案2：用脚本自动化清理扩展字段

编写简单脚本（Node.js/Python均可）遍历OpenAPI Schema，批量删除x-implements字段，将脚本集成到交付流水线实现自动化处理。

示例Node.js脚本（依赖js-yaml包）：

const fs = require('fs');
const yaml = require('js-yaml');

// 读取原始OpenAPI文件
const rawDoc = fs.readFileSync('./src/main/resources/openapi.yaml', 'utf8');
const openapiDoc = yaml.load(rawDoc);

// 遍历所有Schema，移除x-implements字段
if (openapiDoc.components?.schemas) {
  Object.values(openapiDoc.components.schemas).forEach(schema => {
    delete schema['x-implements'];
  });
}

// 写入清理后的文件
fs.writeFileSync('./target/openapi-client.yaml', yaml.dump(openapiDoc, { indent: 2 }));

执行脚本后即可得到供客户使用的干净版本，原文件保持内部开发所需的完整配置。

方案3：用Maven Profile区分内部/外部构建

在pom.xml中配置两个Profile，分别对应内部开发和外部交付场景，通过资源过滤自动控制x-implements字段的存在：

1. 先修改OpenAPI文件，将x-implements改为可替换的变量：

Pet:
  ${x-implements}
  type: object
  required:
    - name
  properties:
    id:
      type: integer
      format: int64
    # ... 其他属性

2. 在pom.xml中配置Profile：

<profiles>
    <profile>
        <id>internal</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <x-implements>x-implements: ['com.petstore.PetInterface']</x-implements>
        </properties>
    </profile>
    <profile>
        <id>external</id>
        <properties>
            <x-implements></x-implements>
        </properties>
    </profile>
</profiles>

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
            <includes>
                <include>openapi.yaml</include>
            </includes>
        </resource>
    </resources>
</build>

• 执行mvn package（默认internal Profile）：生成保留x-implements的文件，供内部代码生成使用
• 执行mvn package -P external：生成移除x-implements的文件，用于客户交付

内容的提问来源于stack exchange，提问作者René Winkler