# springdoc-openapi-ui

**Repository Path**: wxpid1/springdoc-openapi-ui

## Basic Information

- **Project Name**: springdoc-openapi-ui
- **Description**: springdoc-openapi-ui项目扩展
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/wxpid1/springdoc-openapi-ui
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WXP SpringDoc OpenAPI UI

基于 SpringDoc OpenAPI 的 Swagger UI 扩展库，提供本地分组配置和自定义 Swagger 配置接口。

## 项目简介

WXP SpringDoc OpenAPI UI 是一个 Spring Boot  starter 库，基于 [springdoc-openapi](https://github.com/springdoc/springdoc-openapi) 进行扩展，主要功能包括：

- **本地分组支持**：支持配置本地 API 分组
- **自定义 Swagger 配置端点**：提供 `/v3/api-docs/swagger-config` 接口获取 Swagger 配置
- **配置属性扩展**：继承 SpringDocConfigProperties 并提供额外的配置能力

## 技术栈

- Java 8+
- Spring Boot
- SpringDoc OpenAPI
- Swagger UI

## 快速开始

### Maven 依赖

```xml
<dependency>
    <groupId>io.gitee.wxpid1</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>
```

### 配置示例

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

```yaml
springdoc:
  # 是否启用（默认 true）
  enabled: true
  # 本地分组配置
  local-group: true
  local-group-configs:
    - group: "user-api"
      file: "user-api.json"
      order: 1
    - "order-api"
      file: "order-api.json"
      order: 2
```

## 配置说明

### 配置属性

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `springdoc.enabled` | boolean | `true` | 是否启用 |
| `springdoc.local-group` | boolean | `false` | 是否启用本地分组 |
| `springdoc.local-group-configs` | Set | - | 本地分组配置集合 |

### 分组配置 (WxpSpringDocGroupConfig)

| 属性 | 类型 | 说明 |
|------|------|------|
| `file` | String | API 配置文件路径 |
| `order` | Integer | 排序顺序 |

## API 端点

### 获取 Swagger 配置

```
GET /v3/api-docs/swagger-config
```

返回 Swagger UI 所需的配置信息。

## 使用示例

创建一个基本的 REST 控制器：

```java
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Tag(name = "用户管理", description = "用户相关接口")
public class UserController {

    @Operation(summary = "获取用户信息")
    @GetMapping("/user/hello")
    public String hello() {
        return "Hello, World!";
    }
}
```

访问 Swagger UI：`http://localhost:8080/swagger-ui.html`

## 许可证

本项目基于 MIT 许可证开源，详情请查看 [LICENSE](LICENSE) 文件。

## 参与贡献

欢迎提交 Issue 和 Pull Request！