SpringBoot 2.7集成Redoc失败及离线文档预览咨询

问题背景 #

在SpringBoot 2.7（Java 11）项目中尝试用Redoc替代Swagger实现个性化接口文档，目前遇到Redoc无法加载HTML模板的错误，提示Something went wrong... Failed to fetch，参考相关方案后仍未解决。同时因项目无法本地运行，需了解IntelliJ或浏览器的离线预览方案。

错误详情 #

Something went wrong...
Failed to fetch
堆栈跟踪：
Error: Failed to fetch
at t.BaseResolver. (https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js:2:31063)
at Generator.throw ()
at s (https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js:2:28890)
ReDoc版本：2.1.3，Commit：b2d8e0f

用户现有配置 #

application.properties #

server.port=4949

springdoc.api-docs.path=/api-docs
spring.web.resources.static-locations=classpath:/custom/

#springdoc.api-docs.enabled=true
#springdoc.swagger-ui.path=/swagger-ui.html
#springdoc.api-docs.path=/api-docs
#springdoc.swagger-ui.enabled=true
#springdoc.swagger-ui.operationsSorter=method
#springdoc.swagger-ui.tryItOutEnabled=true
#springdoc.swagger-ui.filter=false
#springdoc.swagger-ui.tagsSorter=alpha
#springdoc.swagger-ui.validatorUrl=none
#springdoc.swagger-ui.defaultModelRendering=model
#springdoc.swagger-ui.docExpansion=full

静态资源配置类 #

@Configuration
@EnableWebMvc
public class Static_ResourceHandler implements WebMvcConfigurer {

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {

    registry
            .addResourceHandler("/static/**") 
            .addResourceLocations("classpath:/static/") // Default Static Loaction
            .setCachePeriod( 3600 )
            .resourceChain(true) //
            .addResolver(new GzipResourceResolver())
            .addResolver(new PathResourceResolver()); 

    registry
            .addResourceHandler("/templates/**") 
            .addResourceLocations("classpath:/resources/static/");
}

index.html（路径：resources/static/index.html） #

<!DOCTYPE html>
<html>
<head>
<title>Redoc</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">

<style>
    body {
        margin: 0;
        padding: 0;
    }
</style>
</head>
<body>

<redoc spec-url='http://localhost:4949/api-docs'></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"> 
</script>
</body>
</html>

SpringBoot依赖 #

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

解决方案 #

一、修复跨域配置不匹配问题 #

你的Spring配置中springdoc.api-docs.path=/api-docs，但跨域规则却映射了/v3/api-docs，导致Redoc请求被拦截。修正跨域配置：

@Configuration
@EnableWebMvc
public class Static_ResourceHandler implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api-docs")
                .allowedOrigins("*")
                .allowedMethods("GET")
                .allowCredentials(true);
    }

    // 保留原有的静态资源配置
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry
                .addResourceHandler("/static/**")
                .addResourceLocations("classpath:/static/")
                .setCachePeriod(3600)
                .resourceChain(true)
                .addResolver(new GzipResourceResolver())
                .addResolver(new PathResourceResolver());

        registry
                .addResourceHandler("/templates/**")
                .addResourceLocations("classpath:/resources/static/");
    }
}

二、修正静态资源路径配置 #

application.properties中设置的spring.web.resources.static-locations=classpath:/custom/未包含默认静态目录，导致Spring无法找到resources/static/index.html。二选一修改：

1. 将index.html移动到resources/custom/目录下；
2. 修改配置添加默认静态路径：

spring.web.resources.static-locations=classpath:/custom/,classpath:/static/

三、离线预览方案 #

1. 浏览器直接离线预览

• 在可运行环境中访问/api-docs，将返回的JSON内容保存为openapi.json，放入resources/static/目录；
• 修改index.html中的spec-url为本地文件路径：

<redoc spec-url='./openapi.json'></redoc>

• 直接用浏览器打开index.html即可离线查看文档。

2. IntelliJ中预览

• 在IntelliJ中找到resources/static/index.html，右键选择Open in Browser，直接在浏览器中打开（需先替换spec-url为本地JSON文件）。

四、自定义CSS配置方法 #

1. 在resources/static/下创建css目录，放入自定义样式文件（如custom-redoc.css）；
2. 在index.html的<head>中引入：

<link rel="stylesheet" href="./css/custom-redoc.css">

3. 覆盖Redoc默认样式需使用更具体的选择器，示例：

/* 修改Redoc标题样式 */
.redoc-wrap .api-title {
    color: #2c3e50;
    font-size: 28px;
}

内容的提问来源于stack exchange，提问作者Mohamed amine ben hassen