当前位置：首页 > news >正文

yudao-swagger-new-ui配置终极指南：自定义路径、认证Token与分组管理

news 2026/5/11 23:50:11

yudao-swagger-new-ui配置终极指南：自定义路径、认证Token与分组管理

【免费下载链接】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 2x、Spring Boot 3x，未来还将支持Python、Go等语言的Swagger文档。本文将为您提供一份全面的配置指南，帮助您轻松实现自定义路径、认证Token设置与API分组管理，让API文档管理更加高效便捷。

认识yudao-swagger-new-ui界面

yudao-swagger-new-ui提供了简洁直观的界面，支持明暗两种主题模式，让开发者可以根据自己的喜好和使用环境进行切换。

图1：yudao-swagger-new-ui深色主题界面，展示了API接口列表、参数配置和请求发送区域

图2：yudao-swagger-new-ui浅色主题界面，提供了与深色主题相同的功能，但采用了明亮的配色方案

快速开始：项目集成

要在您的项目中集成yudao-swagger-new-ui，首先需要克隆仓库：

git clone https://gitcode.com/yudaocode/yudao-swagger-new-ui

然后根据您使用的Spring Boot版本，选择相应的示例项目作为参考：

Spring Boot 2x示例：examples/yudao-swagger-ui-spring-boot2-example
Spring Boot 3x示例：examples/yudao-swagger-ui-spring-boot3-example

自定义访问路径

yudao-swagger-new-ui允许您自定义UI的访问路径，满足不同项目的需求。通过修改配置文件中的paths属性，您可以设置一个或多个访问路径。

单一路径配置

在application.properties或application.yml中添加以下配置：

swagger-new-ui.paths=/api-docs.html

多路径配置

如果需要多个访问路径，可以使用逗号分隔：

swagger-new-ui.paths=/swagger-ui.html,/api-docs.html,/docs

配置类SwaggerUiProperties.java中的getPathList()方法会自动处理逗号分隔的路径，将其转换为路径列表。

认证Token设置

为了保护API文档的安全，yudao-swagger-new-ui支持配置认证Token。您可以通过injectConfig属性将认证信息注入到UI中。

配置固定Token

在配置文件中添加：

swagger-new-ui.inject-config.authorization=Bearer your-fixed-token-here

动态Token配置

如果需要更灵活的Token管理，可以通过代码动态设置：

@Configuration public class SwaggerConfig { @Bean public SwaggerUiProperties swaggerUiProperties() { SwaggerUiProperties properties = new SwaggerUiProperties(); Map<String, Object> injectConfig = new HashMap<>(); // 这里可以从环境变量或其他配置源获取Token injectConfig.put("authorization", "Bearer " + System.getenv("API_TOKEN")); properties.setInjectConfig(injectConfig); return properties; } }

API分组管理

随着项目规模的增长，API数量会不断增加，合理的分组管理可以提高文档的可读性和使用效率。

配置分组API路径

yudao-swagger-new-ui默认的分组API路径为/swagger-new-ui/groups，您可以通过以下配置修改：

swagger-new-ui.groups-api-path=/api/swagger/groups

实现分组逻辑

在您的Swagger配置类中，可以通过Docket对象创建不同的API分组：

@Configuration @OpenAPIDefinition( info = @Info( title = "示例API", version = "v1", description = "这是一个示例API文档" ) ) public class SwaggerConfig { @Bean public Docket userApi() { return new Docket(DocumentationType.OAS_30) .groupName("用户管理") .select() .apis(RequestHandlerSelectors.basePackage("cn.coget.examples.controller.user")) .paths(PathSelectors.any()) .build(); } @Bean public Docket productApi() { return new Docket(DocumentationType.OAS_30) .groupName("商品管理") .select() .apis(RequestHandlerSelectors.basePackage("cn.coget.examples.controller.product")) .paths(PathSelectors.any()) .build(); } }