SpringDoc OpenAPI中路径变量冲突导致Swagger UI无法渲染的问题分析

问题背景

在使用SpringDoc OpenAPI为Spring Boot应用生成API文档时，开发者可能会遇到Swagger UI页面无法正常渲染的情况。特别是当控制器中包含以多个路径变量结尾的端点时，会出现SyntaxError: JSON.parse: unexpected character错误，导致整个Swagger UI页面无法加载。

问题现象

当控制器中存在类似以下端点定义时，Swagger UI页面将无法正常渲染：

@GetMapping(value = "{prefix}/{suffix}")
public ResponseEntity<Void> getByComplexId(
    @PathVariable("prefix") String prefix,
    @PathVariable("suffix") String suffix
) {
    return ResponseEntity.ok().build();
}

而以下端点定义则不会导致问题：

@GetMapping(value = "{id}")
public ResponseEntity<Void> getById(@PathVariable("id") String id) {
    return ResponseEntity.ok().build();
}

@GetMapping(value = "{prefix}/{suffix}/AAA")
public ResponseEntity<Void> getByComplexIdAndFiller(
    @PathVariable("prefix") String prefix,
    @PathVariable("suffix") String suffix
) {
    return ResponseEntity.ok().build();
}

根本原因分析

这个问题实际上是由于路径冲突造成的。SpringDoc OpenAPI默认会在应用的根路径下暴露Swagger UI页面（通常是/swagger-ui.html）。当开发者定义的API端点也位于根路径下，并且使用多个路径变量时（如/{prefix}/{suffix}），这个端点会与SpringDoc OpenAPI自身的端点产生冲突。

具体来说：

1. 当访问/swagger-ui.html时，Spring MVC会错误地将这个请求路由到开发者定义的/{prefix}/{suffix}端点，而不是SpringDoc OpenAPI提供的Swagger UI页面。

2. 这种路由冲突导致浏览器无法获取正确的Swagger UI资源，从而出现JSON解析错误或其他异常。

解决方案

方案一：修改API端点路径

将可能产生冲突的API端点移动到特定的路径前缀下，避免与根路径冲突：

@RestController
@RequestMapping("/api")
public class HelloController {
    
    @GetMapping("/{prefix}/{suffix}")
    public ResponseEntity<Void> getByComplexId(
        @PathVariable String prefix,
        @PathVariable String suffix
    ) {
        return ResponseEntity.ok().build();
    }
}

方案二：修改Swagger UI的访问路径

在应用配置中指定Swagger UI的自定义访问路径：

springdoc.swagger-ui.path=/api-docs/swagger-ui.html

然后通过以下URL访问Swagger UI： http://localhost:8080/api-docs/swagger-ui/index.html

方案三：使用不同的HTTP方法

虽然这不是根本解决方案，但可以将冲突端点改为使用POST方法：

@PostMapping(value = "{prefix}/{suffix}")
public ResponseEntity<Void> createResource(
    @PathVariable String prefix,
    @PathVariable String suffix
) {
    return ResponseEntity.ok().build();
}

最佳实践建议

1. 为API添加统一前缀：建议所有业务API都放在特定前缀下（如/api），避免与框架端点冲突。

2. 合理设计URL结构：尽量避免在URL末尾使用多个路径变量，可以考虑使用查询参数或其他设计。

3. 了解框架默认端点：在使用任何框架时，都应该了解它会暴露哪些默认端点，避免与之冲突。

4. 测试Swagger UI可用性：在添加新端点后，应该立即验证Swagger UI是否仍然可以正常访问。

总结

SpringDoc OpenAPI与自定义API端点之间的路径冲突是一个常见但容易被忽视的问题。通过理解框架的工作原理和合理设计API路径结构，可以避免这类问题的发生。本文提供的解决方案不仅解决了Swagger UI无法渲染的问题，也为API设计提供了良好的实践指导。