Quarkus配置OpenApi自定义静态文件名的可行方案咨询

我正在使用Java 11搭配Quarkus框架，尝试通过静态文件配置Swagger的OpenApi规范。Quarkus官方文档推荐使用META-INF/openapi.yml文件，但我希望将该.yml文件命名为我的微服务名称。目前仅能通过配置额外文档目录（如META-INF）来实现，该方式会扫描指定文件夹下的.yaml/.yml及.json文件，但我觉得这是一种临时解决方案。请问是否可以配置Quarkus直接扫描自定义文件名而非文件夹？

解决方案 #

目前Quarkus的SmallRye OpenAPI扩展没有直接配置单个自定义文件名的官方参数，但可以用两种更优雅的方式替代文件夹扫描的临时方案：

1. 构建时自动重命名文件 #

在构建过程中把你的微服务命名的.yml文件自动改成openapi.yml，放到META-INF目录下就行。用Maven或Gradle都能实现：

• Maven配置：借助maven-resources-plugin在资源处理阶段完成重命名：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <version>3.3.1</version>
    <executions>
        <execution>
            <id>rename-openapi-file</id>
            <phase>process-resources</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>${project.build.outputDirectory}/META-INF</outputDirectory>
                <resources>
                    <resource>
                        <directory>src/main/resources</directory>
                        <includes>
                            <include>my-service-name.yml</include>
                        </includes>
                        <filtering>false</filtering>
                        <rename>
                            <from>my-service-name.yml</from>
                            <to>openapi.yml</to>
                        </rename>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>

• Gradle配置：在processResources任务里加一段重命名逻辑：

processResources {
    filesMatching('my-service-name.yml') {
        rename { 'openapi.yml' }
        into 'META-INF'
    }
}

2. 自定义OpenAPI加载逻辑 #

实现Quarkus提供的OpenApiConfigCustomizer接口，手动加载指定文件名的OpenAPI文件，还能支持自定义模型和自动生成模型的合并：

import io.quarkus.smallrye.openapi.runtime.OpenApiConfigCustomizer;
import io.smallrye.openapi.api.OpenApiConfig;
import io.smallrye.openapi.api.util.OpenApiLoader;
import org.eclipse.microprofile.openapi.models.OpenAPI;
import jakarta.enterprise.context.ApplicationScoped;
import java.io.IOException;
import java.io.InputStream;

@ApplicationScoped
public class CustomOpenApiLoader implements OpenApiConfigCustomizer {

    @Override
    public void customize(OpenApiConfig config, OpenAPI model) {
        // 替换成你的微服务文件名
        String customFileName = "my-service-name.yml";
        try (InputStream is = Thread.currentThread().getContextClassLoader().getResourceAsStream(customFileName)) {
            if (is != null) {
                OpenAPI customModel = OpenApiLoader.load(is);
                // 把自定义模型的内容合并到默认模型里，按需调整字段
                model.setInfo(customModel.getInfo());
                model.setPaths(customModel.getPaths());
            }
        } catch (IOException e) {
            throw new RuntimeException("加载自定义OpenAPI文件失败", e);
        }
    }
}

方案选择 #

• 如果只是单纯想换文件名，第一种构建时重命名的方案最轻便，不用加额外代码；
• 如果需要动态加载文件、合并多个OpenAPI模型，第二种自定义加载逻辑的方式更灵活。

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