yudao-swagger-new-ui开发者深度剖析：自动配置原理与SpringDoc适配机制
yudao-swagger-new-ui开发者深度剖析：自动配置原理与SpringDoc适配机制
【免费下载链接】yudao-swagger-new-uiNEW UI 全新一代的 Swagger UI 支持所有功能，兼容spring boot2x、spring boot3x，未来支持 python、go swagger项目地址: https://gitcode.com/yudaocode/yudao-swagger-new-ui
yudao-swagger-new-ui是一款全新一代的Swagger UI，支持所有功能，兼容Spring Boot 2.x、Spring Boot 3.x，未来还将支持Python、Go等语言的Swagger。本文将深入剖析其自动配置原理与SpringDoc适配机制，帮助开发者更好地理解和使用这款工具。
自动配置核心组件
SwaggerUiAutoConfiguration类解析
yudao-swagger-new-ui的自动配置核心在于SwaggerUiAutoConfiguration类，该类位于yudao-swagger-new-ui-boot-starter/src/main/java/cn/coget/swagger/autoconfigure/SwaggerUiAutoConfiguration.java。它使用了@Configuration注解标记为配置类，@ConditionalOnWebApplication确保仅在Web应用中生效，@EnableConfigurationProperties(SwaggerUiProperties.class)启用配置属性绑定。
该类实现了WebMvcConfigurer接口，主要完成以下工作：
- 配置静态资源处理器，将静态资源路径映射到classpath:/static/
- 定义动态HTML路由，支持注入动态信息到HTML页面
- 配置Swagger分组信息路由，兼容不同版本的SpringDoc
SwaggerUiProperties配置属性
配置属性类SwaggerUiProperties位于yudao-swagger-new-ui-boot-starter/src/main/java/cn/coget/swagger/autoconfigure/SwaggerUiProperties.java，使用@ConfigurationProperties(prefix = "swagger-new-ui")注解，可以通过application.properties或application.yml进行配置。
主要配置项包括：
paths：Swagger UI访问路径，支持多个路径（逗号分割），默认为"/swagger-new-ui.html"groupsApiPath：分组API路径，默认为"/swagger-new-ui/groups"baseUrl：Swagger UI的基础URL路径，默认为"/"apiPath：API文档的路径，默认为"/v3/api-docs"injectConfig：需要注入到HTML页面的动态信息
自动配置实现原理
静态资源处理
在SwaggerUiAutoConfiguration类的addResourceHandlers方法中，通过ResourceHandlerRegistry注册静态资源处理器：
@Override public void addResourceHandlers(ResourceHandlerRegistry registry) { String staticPath = extractStaticPath(properties.getGroupsApiPath()); registry.addResourceHandler(staticPath + "/**") .addResourceLocations("classpath:/static/") .setCachePeriod(0) .resourceChain(true); }该方法从groupsApiPath中提取静态资源路径，默认情况下会将"/swagger-new-ui/**"路径映射到classpath:/static/目录，确保Swagger UI的静态资源能够被正确访问。
动态HTML路由配置
swaggerUiHtmlRouter方法定义了动态HTML路由，支持多个路径（逗号分割）：
@Bean public RouterFunction<ServerResponse> swaggerUiHtmlRouter() { RouterFunction<ServerResponse> router = null; for (String htmlPath : properties.getPathList()) { RouterFunction<ServerResponse> pathRouter = route(GET(htmlPath), request -> { // 读取静态HTML模板并注入动态信息 // ... }); // 合并路由 // ... } return router; }该方法会为每个配置的HTML路径创建一个路由，当访问这些路径时，会读取静态HTML模板，并注入动态配置信息到页面中。
动态信息注入
injectDynamicInfo方法负责将配置信息注入到HTML内容中：
private String injectDynamicInfo(String htmlContent, ServerRequest request) { Map<String, Object> config = new HashMap<>(); config.put("path", request.path()); config.put("baseUrl", properties.getBaseUrl()); config.put("apiPath", properties.getApiPath()); config.put("groupsPath", properties.getGroupsApiPath()); // 合并用户自定义配置 if (properties.getInjectConfig() != null && !properties.getInjectConfig().isEmpty()) { config.putAll(properties.getInjectConfig()); } // 生成注入脚本 String configJson = objectMapper.writeValueAsString(config); StringBuilder scriptBuilder = new StringBuilder(); scriptBuilder.append("<script>\n"); scriptBuilder.append("window.SWAGGER_UI_CONFIG = ").append(configJson).append(";\n"); scriptBuilder.append("</script>\n"); // 在<head>标签后注入脚本 return htmlContent.replace("<head>", "<head>\n" + scriptBuilder.toString()); }这段代码会将配置信息序列化为JSON，并注入到HTML的<head>标签中，前端JavaScript可以通过window.SWAGGER_UI_CONFIG访问这些配置。
SpringDoc适配机制
分组信息路由
swaggerGroupsRouter方法配置了Swagger分组信息路由：
@Bean public RouterFunction<ServerResponse> swaggerGroupsRouter() { String groupsPath = properties.getGroupsApiPath(); return route(GET(groupsPath), request -> { List<Map<String, String>> groups = new ArrayList<>(); // 添加默认分组 Map<String, String> defaultGroup = new HashMap<>(); defaultGroup.put("name", "default"); defaultGroup.put("displayName", "默认分组"); defaultGroup.put("url", properties.getApiPath()); groups.add(defaultGroup); // 通过ApplicationContext动态获取GroupedOpenApi Bean List<Object> groupedOpenApis = getGroupedOpenApiBeans(); for (Object groupedOpenApi : groupedOpenApis) { String group = getGroupFromGroupedOpenApi(groupedOpenApi); if (group != null) { Map<String, String> groupInfo = new HashMap<>(); groupInfo.put("name", group); groupInfo.put("displayName", group); groupInfo.put("url", properties.getApiPath() + "/" + group); groups.add(groupInfo); } } // 返回分组信息JSON // ... }); }该方法会创建一个路由，当访问groupsApiPath时，会返回所有Swagger分组信息，包括默认分组和通过SpringDoc定义的分组。
多版本SpringDoc兼容
getGroupedOpenApiBeans方法实现了对不同版本SpringDoc的兼容：
private List<Object> getGroupedOpenApiBeans() { List<Object> groupedOpenApis = new ArrayList<>(); // 尝试获取SpringDoc 2.x的GroupedOpenApi (org.springdoc.core.models.GroupedOpenApi) try { Class<?> groupedOpenApiClass = Class.forName("org.springdoc.core.models.GroupedOpenApi"); Map<String, ?> beans = applicationContext.getBeansOfType(groupedOpenApiClass); groupedOpenApis.addAll(beans.values()); } catch (ClassNotFoundException ignored) { // SpringDoc 2.x不存在，尝试1.x } // 尝试获取SpringDoc 1.x的GroupedOpenApi (org.springdoc.core.GroupedOpenApi) try { Class<?> groupedOpenApiClass = Class.forName("org.springdoc.core.GroupedOpenApi"); Map<String, ?> beans = applicationContext.getBeansOfType(groupedOpenApiClass); groupedOpenApis.addAll(beans.values()); } catch (ClassNotFoundException ignored) { // SpringDoc 1.x不存在 } return groupedOpenApis; }这段代码通过反射机制，分别尝试加载SpringDoc 1.x和2.x版本的GroupedOpenApi类，实现了对不同版本SpringDoc的兼容，确保在Spring Boot 2.x和3.x环境下都能正常工作。
分组信息提取
getGroupFromGroupedOpenApi方法通过反射获取GroupedOpenApi的group属性：
private String getGroupFromGroupedOpenApi(Object groupedOpenApi) { try { // SpringDoc 1.x和2.x都有getGroup()方法 Method getGroupMethod = groupedOpenApi.getClass().getMethod("getGroup"); return (String) getGroupMethod.invoke(groupedOpenApi); } catch (Exception e) { // 忽略异常，返回null return null; } }该方法利用了SpringDoc 1.x和2.x版本的GroupedOpenApi都有getGroup()方法这一特性，通过反射调用该方法获取分组名称，实现了对不同版本的兼容。
实际应用展示
yudao-swagger-new-ui提供了现代化的UI界面，支持明暗两种主题，以下是实际界面展示：
深色主题界面展示了API接口列表、参数信息、响应信息以及代码示例等内容，界面简洁明了，操作便捷。
浅色主题同样提供了丰富的功能，包括API搜索、接口测试、响应展示等，满足不同开发者的使用习惯。
总结
yudao-swagger-new-ui通过SwaggerUiAutoConfiguration和SwaggerUiProperties实现了自动配置，通过反射和条件判断实现了对不同版本SpringDoc的兼容，为开发者提供了一个功能强大、易于使用的Swagger UI。其设计思路和实现方式值得我们学习和借鉴，特别是在处理兼容性和动态配置方面的经验。
如果你想开始使用yudao-swagger-new-ui，可以通过以下命令克隆仓库：
git clone https://gitcode.com/yudaocode/yudao-swagger-new-ui然后根据项目文档进行配置和使用，体验这款全新一代的Swagger UI带来的便捷与高效。
【免费下载链接】yudao-swagger-new-uiNEW UI 全新一代的 Swagger UI 支持所有功能，兼容spring boot2x、spring boot3x，未来支持 python、go swagger项目地址: https://gitcode.com/yudaocode/yudao-swagger-new-ui
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考