{"id":47164999,"url":"https://github.com/yudaocode/yudao-swagger-new-ui","last_synced_at":"2026-03-13T04:04:56.882Z","repository":{"id":343675356,"uuid":"1173428960","full_name":"yudaocode/yudao-swagger-new-ui","owner":"yudaocode","description":"NEW UI 全新一代的 Swagger UI 支持所有功能，兼容spring boot2x、spring boot3x，未来支持 python、go swagger","archived":false,"fork":false,"pushed_at":"2026-03-11T09:59:03.000Z","size":2177,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-11T16:26:54.390Z","etag":null,"topics":["new-ui","swagger-ui","yudao-swagger-new-ui"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yudaocode.png","metadata":{"files":{"readme":"README-CN.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T11:01:51.000Z","updated_at":"2026-03-11T09:59:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yudaocode/yudao-swagger-new-ui","commit_stats":null,"previous_names":["yudaocode/yudao-swagger-new-ui"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yudaocode/yudao-swagger-new-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yudaocode%2Fyudao-swagger-new-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yudaocode%2Fyudao-swagger-new-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yudaocode%2Fyudao-swagger-new-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yudaocode%2Fyudao-swagger-new-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yudaocode","download_url":"https://codeload.github.com/yudaocode/yudao-swagger-new-ui/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yudaocode%2Fyudao-swagger-new-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30457986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T03:55:51.346Z","status":"ssl_error","status_checked_at":"2026-03-13T03:55:33.055Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["new-ui","swagger-ui","yudao-swagger-new-ui"],"created_at":"2026-03-13T04:04:56.147Z","updated_at":"2026-03-13T04:04:56.869Z","avatar_url":"https://github.com/yudaocode.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![home](./docs/img/swagger-home-dark.png)\n\n# NEW UI\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/img/logo.svg\" alt=\"Yudao Swagger UI Logo\" height=\"120\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Compatible with Spring Boot 2.x \u0026 3.x\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#特性\"\u003e特性\u003c/a\u003e •\n  \u003ca href=\"#快速开始\"\u003e快速开始\u003c/a\u003e •\n  \u003ca href=\"#配置说明\"\u003e配置说明\u003c/a\u003e •\n  \u003ca href=\"#本地开发\"\u003e本地开发\u003c/a\u003e •\n  \u003ca href=\"#技术栈\"\u003e技术栈\u003c/a\u003e •\n   \u003ca href=\"https://atomgit.com/yudaocode/yudao-swagger-new-ui\"\u003eAtomGit\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## 特性\n\n- 🎨 **现代化 UI** - 基于 React 19 构建，界面美观易用，支持亮色/暗色主题\n- 🔧 **高度可配置** - 支持自定义路径、API 地址等配置\n- 📦 **双版本支持** - 同时支持 Spring Boot 2.x 和 3.x，使用统一的 Starter\n- 🚀 **零侵入** - 无需修改现有代码，引入依赖即可使用\n- 🌐 **分组支持** - 完整支持 SpringDoc 分组功能\n- ⚡ **动态注入** - 支持向页面注入动态配置\n- 🌙 **主题切换** - 内置亮色/暗色主题，自动保存偏好\n- 📱 **可调整侧边栏** - 支持拖拽调整侧边栏宽度\n- 🔐 **认证支持** - 支持 Bearer Token 认证\n- 💾 **状态持久化** - 自动保存主题、分组、侧边栏宽度等偏好设置\n\n## 界面预览\n\n| 暗色主题 | 亮色主题 |\n|----------|----------|\n| ![暗色主题](docs/img/swagger-home-dark.png) | ![亮色主题](docs/img/swagger-home-light.png) |\n\n## 快速开始\n\n### 环境要求\n\n| 组件 | 版本要求 |\n|------|----------|\n| Java | 8+ (Spring Boot 2.x) / 17+ (Spring Boot 3.x) |\n| Spring Boot | 2.7.x 或 3.x |\n| SpringDoc | 1.7.0+ (Boot 2) / 2.3.0+ (Boot 3) |\n\n### 1. 引入依赖\n\n#### Maven\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecn.coget\u003c/groupId\u003e\n    \u003cartifactId\u003eyudao-swagger-new-ui-boot-starter\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.4-RELEASE\u003c/version\u003e\n    \u003ctype\u003epom\u003c/type\u003e\n\u003c/dependency\u003e\n```\n\n#### Gradle\n\n```groovy\nimplementation 'cn.coget:yudao-swagger-new-ui-boot-starter:1.0.4-RELEASE'\n```\n\n### 2. 添加 SpringDoc 依赖\n\n根据你的 Spring Boot 版本，添加对应的 SpringDoc 依赖：\n\n#### Spring Boot 2.x\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springdoc\u003c/groupId\u003e\n    \u003cartifactId\u003espringdoc-openapi-webmvc-core\u003c/artifactId\u003e\n    \u003cversion\u003e1.7.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n#### Spring Boot 3.x\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springdoc\u003c/groupId\u003e\n    \u003cartifactId\u003espringdoc-openapi-starter-webmvc-api\u003c/artifactId\u003e\n    \u003cversion\u003e2.8.4\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### 3. 启动应用\n\n启动 Spring Boot 应用后，访问以下地址：\n\n```\nhttp://localhost:8080/swagger-new-ui.html\n```\n\n## 配置说明\n\n### 完整配置示例\n\n在 `application.yml` 中添加以下配置：\n\n```yaml\nswagger-new-ui:\n  # Swagger UI 访问路径，支持多个路径（逗号分割）\n  paths: /swagger-new-ui.html,/swagger-ui.html,/doc.html\n  # 基础 URL 路径，适用于有 context-path 的场景(如果有前缀需要设置一下)\n  base-url: /\n  # OpenAPI 文档的 API 路径(默认不用管)\n  api-path: /v3/api-docs\n```\n\n### 配置项说明\n\n| 配置项 | 说明 | 默认值 |\n|--------|------|--------|\n| `paths` | Swagger UI 访问路径，支持多个路径（逗号分割） | `/swagger-new-ui.html` |\n| `groups-api-path` | 分组 API 的访问路径 | `/swagger-new-ui/groups` |\n| `base-url` | 应用的基础 URL 路径，适用于有 context-path 的场景 | `/` |\n| `api-path` | OpenAPI 文档的 API 路径 | `/v3/api-docs` |\n| `inject-config` | 自定义注入到页面的配置，可通过 `window.SWAGGER_UI_CONFIG` 访问 | `{}` |\n\n### 配合 context-path 使用\n\n如果应用配置了 `context-path`，需要同步配置 `base-url`：\n\n```yaml\nserver:\n  servlet:\n    context-path: /admin\n\nswagger-new-ui:\n  base-url: ${server.servlet.context-path}\n  paths: swagger-new-ui.html,swagger-ui.html,doc.html\n```\n\n此时访问地址为：`http://localhost:8080/admin/swagger-new-ui.html`\n\n## 使用示例\n\n### 基础 Controller 示例\n\n```java\n@RestController\n@RequestMapping(\"/api/users\")\n@Tag(name = \"用户管理\", description = \"用户相关接口\")\npublic class UserController {\n\n    @GetMapping(\"/{id}\")\n    @Operation(summary = \"获取用户信息\", description = \"根据用户ID获取用户详细信息\")\n    public Result\u003cUserVO\u003e getUser(\n            @Parameter(description = \"用户ID\", required = true)\n            @PathVariable Long id) {\n        // ...\n    }\n\n    @PostMapping\n    @Operation(summary = \"创建用户\")\n    public Result\u003cUserVO\u003e createUser(@RequestBody UserCreateDTO dto) {\n        // ...\n    }\n}\n```\n\n### 配置分组\n\n通过 `GroupedOpenApi` 配置 API 分组：\n\n```java\n@Configuration\npublic class SwaggerConfig {\n\n    @Bean\n    public OpenAPI customOpenAPI() {\n        return new OpenAPI()\n                .info(new Info()\n                        .title(\"API 文档\")\n                        .version(\"1.0\"));\n    }\n\n    @Bean\n    public GroupedOpenApi userApi() {\n        return GroupedOpenApi.builder()\n                .group(\"用户API\")\n                .pathsToMatch(\"/api/users/**\")\n                .build();\n    }\n\n    @Bean\n    public GroupedOpenApi orderApi() {\n        return GroupedOpenApi.builder()\n                .group(\"订单API\")\n                .pathsToMatch(\"/api/orders/**\")\n                .build();\n    }\n}\n```\n\n## 项目结构\n\n```\nyudao-swagger-ui/\n├── yudao-swagger-new-ui-boot-starter/    # Spring Boot Starter 模块\n│   ├── pom.xml\n│   └── src/main/\n│       ├── java/cn/coget/swagger/autoconfigure/\n│       │   ├── SwaggerUiAutoConfiguration.java   # 自动配置类\n│       │   └── SwaggerUiProperties.java          # 配置属性类\n│       └── resources/\n│           ├── META-INF/\n│           │   ├── spring.factories              # Spring Boot 2.x 自动配置\n│           │   └── spring/\n│           │       └── org.springframework.boot.autoconfigure.AutoConfiguration.imports  # Spring Boot 3.x\n│           └── static/                           # Swagger UI 静态资源\n│               ├── index.html\n│               └── assets/\n├── examples/                                    # 示例项目\n│   ├── yudao-swagger-ui-spring-boot2-example/  # Spring Boot 2.x 示例\n│   │   └── src/main/\n│   │       ├── java/cn/coget/examples/\n│   │       │   ├── config/\n│   │       │   ├── controller/\n│   │       │   ├── dto/\n│   │       │   └── vo/\n│   │       └── resources/application.yml\n│   └── yudao-swagger-ui-spring-boot3-example/  # Spring Boot 3.x 示例\n│       └── src/main/\n│           ├── java/cn/coget/examples/\n│           └── resources/application.yml\n├── ui/                                          # 前端源码\n│   ├── src/\n│   │   ├── App.jsx                              # 主应用组件\n│   │   ├── components/                          # React 组件\n│   │   │   ├── Sidebar.jsx                      # 侧边栏\n│   │   │   ├── MainContent.jsx                  # 主内容区\n│   │   │   ├── SettingsModal.jsx               # 设置弹窗\n│   │   │   ├── icons/                          # 图标组件\n│   │   │   └── main-content/                   # 主内容子组件\n│   │   ├── hooks/                              # 自定义 Hooks\n│   │   └── styles/                             # 样式文件\n│   ├── package.json\n│   └── vite.config.js\n└── build.sh                                    # 构建脚本\n```\n\n## 本地开发\n\n### 构建完整项目\n\n使用提供的构建脚本，自动完成前端构建和后端打包：\n\n```bash\n./build.sh\n```\n\n该脚本会：\n1. 构建前端 React 项目（`npm run build:java`）\n2. 将构建产物复制到 Starter 的 static 目录\n3. 使用 JDK 8 编译并安装 Starter 到本地 Maven 仓库\n\n### 前端开发\n\n```bash\ncd ui\n\n# 安装依赖\nnpm install\n\n# 开发模式（带代理）\nnpm run dev\n\n# 构建生产版本（用于 Java 项目）\nnpm run build:java\n\n# 构建标准版本\nnpm run build\n```\n\n开发模式下，Vite 会自动代理以下路径到后端：\n- `/v3/*` → `http://127.0.0.1:8080`\n- `/api/*` → `http://127.0.0.1:8080`\n- `/swagger-new-ui/*` → `http://127.0.0.1:8080`\n\n### 运行示例项目\n\n```bash\n# Spring Boot 2.x 示例\ncd examples/yudao-swagger-ui-spring-boot2-example\nmvn spring-boot:run\n\n# Spring Boot 3.x 示例\ncd examples/yudao-swagger-ui-spring-boot3-example\nmvn spring-boot:run\n```\n\n访问：`http://localhost:8080/admin/swagger-new-ui.html`\n\n### 仅构建后端模块\n\n```bash\ncd yudao-swagger-new-ui-boot-starter\nmvn clean install -DskipTests\n```\n\n### 发布到 Maven 仓库\n\n```bash\nmvn clean deploy\n```\n\n\u003e 注意：需要在 `~/.m2/settings.xml` 中配置仓库认证信息。\n\n## 技术栈\n\n### 前端\n\n| 技术 | 版本 | 说明 |\n|------|------|------|\n| React | 19.x | UI 框架 |\n| Vite | 7.x | 构建工具 |\n| SCSS | - | 样式预处理 |\n| highlight.js | 11.x | 代码高亮 |\n\n### 后端\n\n| 技术 | 版本 | 说明 |\n|------|------|------|\n| Spring Boot | 2.7.x / 3.x | 应用框架 |\n| SpringDoc OpenAPI | 1.7.x / 2.x | API 文档生成 |\n| Java | 8+ / 17+ | 运行环境 |\n\n## 兼容性\n\n| Spring Boot | Java | SpringDoc | Starter |\n|-------------|------|-----------|---------|\n| 2.7.x | 8+ | 1.7.x | ✅ 支持 |\n| 3.x | 17+ | 2.x | ✅ 支持 |\n\nStarter 使用 JDK 8 编译，确保与所有版本兼容。\n\n## 工作原理\n\n### 自动配置机制\n\nStarter 使用 Spring Boot 的自动配置机制：\n\n1. **Spring Boot 2.x**：使用 `META-INF/spring.factories` 注册自动配置\n2. **Spring Boot 3.x**：使用 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`\n\n### 动态 HTML 注入\n\n`SwaggerUiAutoConfiguration` 读取静态的 `index.html` 模板，并注入一个包含 `window.SWAGGER_UI_CONFIG` 的 `\u003cscript\u003e` 标签，其中包含动态配置值。\n\n### SpringDoc 兼容性\n\nStarter 使用反射来检测和适配 SpringDoc 1.x（Spring Boot 2.x）和 SpringDoc 2.x（Spring Boot 3.x）：\n\n- SpringDoc 2.x：`org.springdoc.core.models.GroupedOpenApi`\n- SpringDoc 1.x：`org.springdoc.core.GroupedOpenApi`\n\n两个版本都有 `getGroup()` 方法，通过反射调用。\n\n## 常见问题\n\n### Q: 如何修改默认访问路径？\n\nA: 在 `application.yml` 中配置 `swagger-new-ui.paths`：\n\n```yaml\nswagger-new-ui:\n  paths: /doc.html\n```\n\n### Q: 如何配置认证 Token？\n\nA: 在界面右上角点击设置图标，输入 Bearer Token。\n\n### Q: 如何自定义注入配置？\n\nA: 使用 `inject-config` 配置项：\n\n```yaml\nswagger-new-ui:\n  inject-config:\n    app-name: MyApp\n    app-version: 1.0.0\n```\n\n在前端可通过 `window.SWAGGER_UI_CONFIG` 访问。\n\n### Q: 为什么 Spring Boot 2 和 3 使用同一个 Starter？\n\nA: Starter 使用 JDK 8 编译，同时兼容 Spring Boot 2.x 和 3.x。代码通过反射动态检测 SpringDoc 版本，自动适配不同的 API。\n\n## 贡献指南\n\n欢迎提交 Issue 和 Pull Request！\n\n## License\n\n[MIT License](LICENSE)\n\n\u003cimg src=\"https://bbc-ps.oss-cn-shenzhen.aliyuncs.com/www/new-ui.png\" alt=\"Yudao Swagger UI Logo\" height=\"300\"\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyudaocode%2Fyudao-swagger-new-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyudaocode%2Fyudao-swagger-new-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyudaocode%2Fyudao-swagger-new-ui/lists"}