如何通过Maven从多文件/文件夹生成OpenAPI模型与接口？

问题描述 #

我有多个*.yaml文件，希望通过Maven生成对应的模型和接口。目前我的Maven配置是通过多个execution分别处理单个文件，请问是否可以在单次execution中指定多个文件或文件夹来完成生成？

现有配置 #

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.2.0</version>
    <executions>
        <execution>
            <id>bookApi</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/books.yaml
                </inputSpec>
                <generatorName>spring</generatorName>
                <library>spring-boot</library>
                <modelPackage>com.mhaque.bookstore.model</modelPackage>
                <apiPackage>com.mhaque.bookstore.controller</apiPackage>
                <configOptions>
                    <java8>false</java8>
                    <interfaceOnly>true</interfaceOnly>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
        <execution>
            <id>studentApi</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/students.yaml
                </inputSpec>
                <generatorName>spring</generatorName>
                <library>spring-boot</library>
                <modelPackage>com.mhaque.bookstore.model</modelPackage>
                <apiPackage>com.mhaque.bookstore.controller</apiPackage>
                <configOptions>
                    <java8>false</java8>
                    <interfaceOnly>true</interfaceOnly>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

期望配置示例 #

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.2.0</version>
    <executions>
        <execution>
            <id>bookstoreApi</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/books.yaml,
                    ${project.basedir}/src/main/resources/students.yaml
                </inputSpec> <!--multiple files or folder-->
                <generatorName>spring</generatorName>
                <library>spring-boot</library>
                <modelPackage>com.mhaque.bookstore.model</modelPackage>
                <apiPackage>com.mhaque.bookstore.controller.v1</apiPackage>
                <configOptions>
                    <java8>false</java8>
                    <interfaceOnly>true</interfaceOnly>
                    <dateLibrary>java8</dateLibrary>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

解决方案 #

完全可以在单次execution中处理多个YAML文件或整个文件夹，以下是两种常用实现方式：

1. 逗号分隔指定多个文件 #

你期望的配置思路是可行的，只需注意路径格式：逗号需紧跟在前一个文件路径末尾，避免因换行或空格导致路径解析错误。示例如下：

<!-- 紧凑写法 -->
<inputSpec>${project.basedir}/src/main/resources/books.yaml,${project.basedir}/src/main/resources/students.yaml</inputSpec>

<!-- 换行保持可读性的写法 -->
<inputSpec>
    ${project.basedir}/src/main/resources/books.yaml,
    ${project.basedir}/src/main/resources/students.yaml
</inputSpec>

2. 指定文件夹自动遍历所有YAML #

如果目标目录下的所有YAML文件都是需要处理的OpenAPI定义，直接指定文件夹路径即可，插件会自动遍历处理其中的所有符合要求的文件：

<inputSpec>${project.basedir}/src/main/resources/</inputSpec>

关键注意事项 #

• 模型名称冲突：若多个YAML文件存在同名模型，生成时会出现覆盖或报错。建议提前确保各文件的模型名称唯一，或通过OpenAPI文件的x-model-package扩展为不同文件的模型指定子包，避免冲突。
• 版本兼容性：你使用的7.2.0版本完全支持多文件/文件夹输入，低版本（如v5之前）可能存在兼容性问题，确认插件版本符合要求即可。

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