如何使用openapi.yaml生成swagger-ui？已有规范文件的配置方法

以下是两种更优雅的方案，替代手动编写/v3/api-docs端点的方式：

方案1：直接让Swagger UI加载本地yaml文件 #

这种方式无需额外编写代码，仅通过配置即可让Swagger UI直接读取你本地的openapi.yaml文件：

1. 将你的openapi.yaml文件放到项目的src/main/resources/static目录下（确保Spring Boot能静态访问到该文件）
2. 在application.yml中添加配置：

springdoc:
  swagger-ui:
    url: /openapi.yaml  # 指定Swagger UI加载的yaml文件路径
    enabled: true
  api-docs:
    enabled: false  # 关闭自动生成的api-docs，避免冲突

如果用application.properties，配置如下：

springdoc.swagger-ui.url=/openapi.yaml
springdoc.swagger-ui.enabled=true
springdoc.api-docs.enabled=false

3. 启动项目后，访问/swagger-ui.html就能看到基于你本地yaml生成的API文档页面。

方案2：绑定本地yaml到默认的/v3/api-docs端点 #

如果你希望保留/v3/api-docs端点，但返回自己的yaml内容，可以通过配置类实现：

1. 编写一个配置类，加载本地yaml文件并转为OpenAPI实例：

import io.swagger.v3.oas.models.OpenAPI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.yaml.snakeyaml.Yaml;

import java.io.IOException;
import java.io.InputStream;

@Configuration
public class CustomOpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() throws IOException {
        // 加载resources目录下的openapi.yaml文件
        ClassPathResource yamlResource = new ClassPathResource("openapi.yaml");
        try (InputStream inputStream = yamlResource.getInputStream()) {
            Yaml yamlParser = new Yaml();
            return yamlParser.loadAs(inputStream, OpenAPI.class);
        }
    }
}

2. 确保application.yml中开启api-docs（默认是开启的），无需额外配置Swagger UI的url，它会自动读取/v3/api-docs的内容：

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true

3. 启动项目后，访问/swagger-ui.html即可看到基于你本地yaml生成的文档，同时/v3/api-docs也会返回你的yaml内容。

依赖说明 #

确保你的Spring Boot项目引入了Springdoc OpenAPI的UI starter（这是当前推荐的Swagger替代方案）：

<!-- Maven依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version> <!-- 使用最新稳定版本 -->
</dependency>

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