# csap-framework-apidoc
**Repository Path**: csap-framework/csap-framework-apidoc
## Basic Information
- **Project Name**: csap-framework-apidoc
- **Description**: 接口文档相关
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 3
- **Created**: 2020-05-18
- **Last Updated**: 2026-11-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# CSAP Framework API Doc
[中文](README.md) | [English](README.en.md)
[](https://search.maven.org/)
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://www.oracle.com/java/technologies/javase-downloads.html)
[](https://spring.io/projects/spring-boot)
一个强大的 Spring Boot API 文档管理框架,提供自动化文档生成、在线测试、多格式导出等功能
## ✨ 特性
- 🚀 **零侵入集成** - 基于注解,无需修改现有代码
- 📝 **自动生成文档** - 扫描 Spring MVC 注解自动生成 API 文档
- 🎨 **现代化界面** - 基于 React 18 + TypeScript + Ant Design 5 的美观 UI
- 🧪 **在线测试** - 内置 API 测试工具,无需 Postman
- 📦 **多格式导出** - 支持 OpenAPI/Swagger、Postman、Markdown、JSON Schema
- 🔍 **参数验证** - 集成 JSR-303 验证规则展示
- 🌲 **多存储策略** - 支持 SQLite、YAML、标准输出等多种持久化方式
- 🔧 **灵活配置** - 丰富的配置选项,满足各种场景需求
- 🎯 **开发工具** - 提供 DevTools 实时预览和配置管理
- 📐 **列宽调整** - DevTools 参数表格支持拖动调整列宽
## 🎯 快速开始
### 环境要求
- JDK 8+(推荐 JDK 8 或 JDK 11)
- Maven 3.x 或 Gradle
- Spring Boot 2.x
### Maven 依赖
**1. API 文档核心依赖(必需)**
```xml
ai.csap.apidoc.boot
csap-apidoc-boot-starter
1.1.0
```
**2. 数据验证依赖(必需)**
如果需要使用 JSR-303 验证规则展示、参数验证等功能,必须添加:
```xml
ai.csap.apidoc.boot
csap-validation-boot-starter
1.1.0
```
此依赖提供:
- ✅ JSR-303 验证注解支持(`@NotNull`、`@NotEmpty`、`@Size` 等)
- ✅ 自定义验证注解(`@Phone`、`@AssertBoolean` 等)
- ✅ 验证错误统一异常处理
- ✅ API 文档中展示验证规则
**3. 可选依赖**
根据需要选择添加:
```xml
ai.csap.apidoc
csap-apidoc-devtools
1.1.0
provided
ai.csap.apidoc
csap-apidoc-ui
1.1.0
provided
```
### 基本配置(推荐使用注解方式)
在你的 Spring Boot 启动类上添加 `@EnableApidoc` 注解:
```java
@SpringBootApplication
@EnableApidoc("com.yourcompany.yourproject")
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
### 参数策略类型
CSAP Apidoc 支持多种参数管理策略,通过 `paramType` 配置:
**1. ANNOTATION 策略(默认 - 推荐)**
```java
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.ANNOTATION // 使用注解定义参数
)
```
- 使用 `@ApiProperty`、`@ApiModelProperty` 等注解定义参数
- 类型安全,IDE 支持,易于维护
- **这是默认且推荐的方式**
**2. SQLite 策略**
```java
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.SQL_LITE, // 参数配置存储在 SQLite
path = "csap-example", // 存储路径
fileName = "example-db" // SQLite 数据库文件名
)
```
- 参数配置存储在 SQLite 数据库
- 支持通过 DevTools 可视化配置参数
- 适合需要动态参数管理的场景
**使用环境变量(推荐用于 path 和 fileName):**
```java
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.SQL_LITE,
path = "${csap.apidoc.path:csap-example}", // 使用环境变量,带默认值
fileName = "${csap.apidoc.filename:example-db}" // 使用环境变量,带默认值
)
```
然后在 `application.yml` 中配置:
```yaml
csap:
apidoc:
path: csap-production # 覆盖路径
filename: prod-db # 覆盖数据库名
```
或使用系统环境变量:
```bash
export CSAP_APIDOC_PATH=/var/data/apidoc
export CSAP_APIDOC_FILENAME=prod-db
```
**3. YAML 策略**
```java
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.YAML, // 参数配置存储在 YAML 文件
path = "csap-docs" // YAML 文件存储路径
)
```
- 参数配置存储在 YAML 文件
- 人类可读,便于版本控制
- 易于手动审查和编辑
**4. 多包路径高级配置**
```java
@EnableApidoc(
apiPackages = {"com.yourcompany.yourproject.controller"}, // API 控制器包
enumPackages = {"com.yourcompany.yourproject.enums"}, // 枚举类包
modelPackages = {"com.yourcompany.yourproject.model"}, // 模型类包
paramType = ApiStrategyType.ANNOTATION, // 策略类型
showChildPackageFlag = true // 扫描子包
)
```
**策略对比:**
| 策略 | 适用场景 | 优点 | 缺点 |
| --------------------- | -------------- | -------------------------- | ---------------- |
| **ANNOTATION** (默认) | 标准 API 文档 | 类型安全、IDE 支持、易维护 | 需要代码注解 |
| **SQL_LITE** | 动态参数管理 | 可视化配置、无需改代码 | 需要数据库文件 |
| **YAML** | 版本控制的文档 | 人类可读、易于审查 | 需要手动编辑文件 |
### 使用注解
在你的 Controller 中添加文档注解:
```java
@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理", description = "用户相关接口")
public class UserController {
@GetMapping("/{id}")
@ApiOperation(value = "获取用户信息", description = "根据用户ID获取用户详细信息")
public Response getUser(@PathVariable Long id) {
// 业务逻辑
// 框架自动识别 @PathVariable、@RequestParam、@RequestBody 参数
return Response.success(user);
}
@PostMapping
@ApiOperation(value = "创建用户", description = "创建新用户")
public Response createUser(@Valid @RequestBody User user) {
// 业务逻辑
// User 类需要用 @ApiModel 标注
// @Valid 会触发验证,验证规则会展示在 API 文档中
return Response.success(createdUser);
}
}
```
### 使用验证注解
在你的实体类中添加验证注解,这些验证规则会自动展示在 API 文档中:
```java
@ApiModel(description = "用户实体")
public class User {
@ApiModelProperty(value = "用户ID", required = true, example = "1001")
private Long id;
@ApiModelProperty(value = "用户名", required = true, example = "张三")
@NotEmpty(message = "用户名不能为空")
@Size(min = 2, max = 20, message = "用户名长度必须在2-20之间")
private String username;
@ApiModelProperty(value = "邮箱", example = "user@example.com")
@Email(message = "邮箱格式不正确")
private String email;
@ApiModelProperty(value = "手机号", example = "13800138000")
@Phone(message = "手机号格式不正确") // 自定义验证注解
private String mobile;
@ApiModelProperty(value = "年龄", example = "25")
@Min(value = 18, message = "年龄必须大于18岁")
@Max(value = 120, message = "年龄必须小于120岁")
private Integer age;
}
```
**支持的验证注解:**
| 注解 | 说明 | 示例 |
| ---------------- | --------------------------- | -------------------------------------- |
| `@NotNull` | 不能为 null | `@NotNull(message = "不能为空")` |
| `@NotEmpty` | 不能为 null 或空字符串/集合 | `@NotEmpty(message = "不能为空")` |
| `@NotBlank` | 不能为 null 或空白字符串 | `@NotBlank(message = "不能为空")` |
| `@Size` | 字符串/集合/数组长度限制 | `@Size(min = 2, max = 20)` |
| `@Min` / `@Max` | 数值最小/最大值 | `@Min(18)` `@Max(120)` |
| `@Email` | 邮箱格式验证 | `@Email(message = "邮箱格式不正确")` |
| `@Pattern` | 正则表达式验证 | `@Pattern(regexp = "^[a-zA-Z0-9]+$")` |
| `@Phone` | 手机号验证(自定义) | `@Phone(message = "手机号格式不正确")` |
| `@AssertBoolean` | 布尔值断言(自定义) | `@AssertBoolean(value = true)` |
### 启动访问
启动应用后,访问以下地址:
- **API 文档界面**: `http://localhost:8080/csap-api.html`
- **API 数据接口**: `http://localhost:8080/csap/apidoc/parent` (树形结构)
- **完整文档接口**: `http://localhost:8080/csap/apidoc` (所有文档)
- **Postman 导出**: `http://localhost:8080/csap/openapi/postman`
## 📦 模块介绍
### 核心模块
| 模块 | 说明 | 主要功能 |
| ------------------------------------------ | ------------- | --------------------------------------------------- |
| **csap-apidoc-annotation** | 注解模块 | 提供`@Api`、`@ApiOperation`、`@ApiModel` 等文档注解 |
| **csap-apidoc-common** | 公共模块 | 通用工具类、常量定义、基础模型 |
| **csap-apidoc-core** | 核心模块 | 文档扫描、解析、生成核心逻辑 |
| **csap-apidoc-boot-starter** | API文档启动器 | API 文档自动配置、快速集成 |
| **csap-validation-boot-starter** | 验证启动器 | JSR-303 验证、自定义验证注解、统一异常处理 |
### 功能模块
| 模块 | 说明 | 主要功能 |
| ---------------------------------- | ----------- | ------------------------ |
| **csap-apidoc-strategy** | 存储策略 | 支持多种文档持久化方式 |
| **csap-apidoc-sqlite** | SQLite 存储 | 基于 SQLite 的文档存储 |
| **csap-apidoc-yaml** | YAML 存储 | 基于 YAML 文件的文档存储 |
| **csap-apidoc-standard** | 标准输出 | 标准格式文档输出 |
| **csap-apidoc-devtools** | 开发工具 | 提供可视化文档管理界面 |
| **csap-apidoc-ui** | Web 前端 | React 实现的文档展示界面 |
| **csap-validation-core** | 验证核心 | JSR-303 验证规则集成 |
## 🔧 高级配置
### 环境变量支持
`path` 和 `fileName` 支持 Spring Boot 占位符语法:
**语法:**
- `${property.name}` - 使用属性值,不存在则报错
- `${property.name:defaultValue}` - 使用属性值或默认值
**示例:**
```java
@EnableApidoc(
value = "com.yourcompany.yourproject",
paramType = ApiStrategyType.SQL_LITE,
path = "${csap.apidoc.data.path:/tmp/apidoc}", // 未配置则使用 /tmp/apidoc
fileName = "${csap.apidoc.db.file:${spring.application.name}}" // 默认使用应用名
)
```
在 `application.yml` 或 `application.properties` 中配置:
```yaml
# application.yml
csap:
apidoc:
data:
path: /var/apidoc/data
db:
file: myapp-docs
```
```properties
# application.properties
csap.apidoc.data.path=/var/apidoc/data
csap.apidoc.db.file=myapp-docs
```
或使用系统环境变量:
```bash
span
```
**优势:**
- ✅ 不同环境(开发/测试/生产)使用不同配置
- ✅ 集中化配置管理
- ✅ 易于通过环境变量覆盖
- ✅ 支持 Docker 和 Kubernetes 部署
### 完整配置示例
**主启动类(必需):**
```java
@SpringBootApplication
@EnableApidoc(
apiPackages = {"com.yourcompany.yourproject.controller"},
enumPackages = {"com.yourcompany.yourproject.enums"},
modelPackages = {"com.yourcompany.yourproject.model"},
type = ApiStrategyType.ANNOTATION,
paramType = ApiStrategyType.ANNOTATION,
fileName = "apidoc.db", // SQLite 文件名
showChildPackageFlag = true
)
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
```
**application.yml(可选,用于 DevTools):**
```yaml
csap:
apidoc:
# DevTools 配置
devtool:
enabled: true # 启用开发工具界面
cache: true # 启用缓存(默认:true)
```
## 📚 文档导出
### 支持的导出格式
- **OpenAPI 3.0 / Swagger** - JSON 和 YAML 格式
- **Postman Collection** - 可直接导入 Postman
- **Markdown** - 美观的文档格式
- **JSON Schema** - 标准的 JSON Schema 格式
- **TypeScript** - 自动生成 TypeScript 类型定义
### 导出示例
```java
@Autowired
private PostmanConverterService postmanService;
public void exportToPostman() {
CsapDocParentResponse apiDoc = apidocService.getApiDoc();
String postmanJson = postmanService.convertToPostmanCollection(apiDoc);
// 保存或返回 JSON
}
```
## 🎨 DevTools 开发工具
### 功能特点
- 🔍 **实时预览** - 实时查看 API 文档变化
- ⚙️ **在线配置** - 可视化配置参数、返回值
- 🧪 **在线测试** - 发送测试请求,查看响应结果
- 📝 **文档编辑** - 可视化编辑 API 文档信息
- 🎯 **字段管理** - 管理可选字段、复用字段配置
### 技术栈
- React 18.2
- TypeScript 5.3
- Vite 5.x
- Ant Design 5.x
- Zustand (状态管理)
- Axios (HTTP 客户端)
### 如何启用 DevTools
**方式一:添加 DevTools 依赖(推荐)**
在你的 `pom.xml` 中添加:
```xml
ai.csap.apidoc
csap-apidoc-devtools
1.1.0
```
启动应用后访问:
- **DevTools 界面**: `http://localhost:8080/csap-api-devtools.html`
**方式二:使用独立 Web 项目**
如果不想在业务项目中引入 DevTools 依赖,可以使用独立的 Web 界面:
```xml
ai.csap.apidoc
csap-apidoc-ui
1.1.0
```
启动应用后访问:
- **Web 界面**: `http://localhost:8080/csap-api.html`
### DevTools 配置选项
在 `application.yml` 中配置:
```yaml
csap:
apidoc:
# DevTools 基本配置
devtool:
enabled: true # 是否启用 DevTools(默认:true)
cache: true # 是否启用缓存(默认:true)
# 接口数据配置(用于网关聚合或远程数据源)
resources:
- name: 本地API # 资源名称
url: /csap/apidoc/parent # API 文档接口地址
version: v1.0 # 版本号(可选)
```
**配置说明:**
- `devtool.enabled`: 控制是否启用 DevTools 功能
- `true`: 启用(开发/测试环境推荐)
- `false`: 禁用(生产环境推荐)
- `devtool.cache`: 控制是否缓存 API 文档数据
- `true`: 启用缓存,提升性能(默认)
- `false`: 禁用缓存,实时刷新数据
- `resources`: 配置多个 API 文档数据源(用于网关聚合场景)
- `name`: 显示名称
- `url`: API 文档接口地址
- `version`: 版本标识
### 生产环境建议
在生产环境中,建议:
1. **禁用 DevTools**(如果引入了 devtools 依赖):
```yaml
csap:
apidoc:
devtool:
enabled: false
```
2. **或者使用 Maven Profile** 在生产环境排除 DevTools 依赖:
```xml
dev
ai.csap.apidoc
csap-apidoc-devtools
1.1.0
```
3. **仅保留文档查看界面**(使用 apidoc-web 模块),不包含编辑功能。
## 📊 架构设计
```
┌─────────────────────────────────────────────────────────┐
│ Spring Boot Application │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Controller │───▶│ Apidoc Core │───│ Storage │ │
│ │ Layer │ │ Scanner │ │ Strategy │ │
│ └────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ │ ▼ ▼ │
│ │ ┌──────────────┐ ┌──────────────┐ │
│ │ │ Annotation │ │ SQLite/ │ │
│ │ │ Processor │ │ YAML/... │ │
│ │ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ REST │───▶│ DevTools │───│ Web UI │ │
│ │ API │ │ Service │ │ (React) │ │
│ └────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
## 🌟 核心注解
### @Api
标注在 Controller 类上,定义 API 分组信息
```java
@Api(tags = "用户管理", description = "用户相关接口")
```
### @ApiOperation
标注在方法上,描述 API 操作
```java
@ApiOperation(value = "获取用户", description = "根据ID获取用户信息")
```
### @ApiModel
标注在实体类上,描述数据模型
```java
@ApiModel(description = "用户实体")
public class User {
// 字段定义
}
```
### @ApiModelProperty
标注在字段上,描述字段属性
```java
@ApiModelProperty(value = "用户ID", required = true, example = "1001")
private Long id;
```
### @EnumValue 和 @EnumMessage
标注在枚举类的字段上
```java
@AllArgsConstructor
@Getter
public enum UserStatus {
ACTIVE(1, "激活"),
DISABLED(2, "禁用");
@EnumValue // 标注 code 字段(存数据库)
private final Integer code;
@EnumMessage // 标注 message 字段(显示说明)
private final String message;
}
```
### @ApiProperty
标注在方法上,为方法参数补充详细文档
```java
@GetMapping("/search")
@ApiOperation(value = "搜索用户")
@ApiProperty(
value = "搜索关键词",
name = "keyword", // 匹配方法参数名
description = "用户名或邮箱关键词",
required = true,
example = "john",
paramType = ParamType.QUERY
)
public Response> search(String keyword) {
// 方法有实际参数 keyword
// @ApiProperty 通过 name="keyword" 匹配这个参数
}
```
### @ApiPropertys
在方法上定义多个参数的文档
```java
@GetMapping("/filter")
@ApiPropertys({
@ApiProperty(name = "minAge", value = "最小年龄", example = "18"),
@ApiProperty(name = "maxAge", value = "最大年龄", example = "60")
})
public Response> filter(Integer minAge, Integer maxAge) {
// 为多个参数补充文档
}
```
> **注意**:
>
> - 对于常规的 `@PathVariable` 和 `@RequestParam`,框架会自动识别
> - `@ApiProperty` 用于补充更详细的文档说明
> - 通过 `name` 属性匹配实际参数名
## 🎯 使用场景
### 场景一:团队协作开发
- **前后端分离** - 前端根据文档开发,无需等待后端完成
- **接口变更通知** - 文档自动更新,减少沟通成本
- **测试支持** - 测试人员直接使用在线测试功能
### 场景二:API 对接
- **第三方集成** - 导出 Postman Collection 给合作方
- **文档交付** - 导出精美的 Markdown 文档
- **类型定义** - 自动生成 TypeScript 类型,前端直接使用
### 场景三:项目维护
- **版本管理** - 记录 API 变更历史
- **快速查询** - 快速定位接口和参数信息
- **代码生成** - 基于文档生成客户端代码
### 场景四:网关聚合文档
在微服务架构或网关场景下,统一管理多个服务的 API 文档:
- **多服务聚合** - 在网关层聚合所有微服务的 API 文档
- **统一入口** - 一个界面查看所有服务的接口文档
- **快速切换** - 通过下拉框快速切换不同服务的文档
#### 配置示例
在网关项目的 `application.yml` 中配置:
```yaml
csap:
apidoc:
resources:
- name: 总后台API
url: /example-admin-api/csap/apidoc/parent
version: v1.0
- name: 门店API
url: /example-store-api/csap/apidoc/parent
version: v1.0
- name: 其他API
url: /example-other-api/csap/apidoc/parent
version: v1.0
```
**工作原理:**
1. 网关层配置所有微服务的文档接口地址
2. 前端界面提供服务选择下拉框
3. 用户选择不同服务时,动态加载对应的 API 文档
4. 无需在每个服务中单独查看文档
**适用场景:**
- Spring Cloud Gateway 微服务架构
- Nginx 网关统一入口
- Kong、APISIX 等 API 网关
- 多租户 SaaS 系统
## 🔨 开发计划
### 已完成 ✅
- [X] 核心文档生成功能
- [X] 多种注解支持
- [X] DevTools 开发工具
- [X] React 前端界面
- [X] Postman 格式转换
- [X] 多存储策略支持
- [X] 参数验证集成
### 进行中 🚧
- [ ] API 在线测试增强
- [ ] Mock 数据生成
- [ ] JSON Schema 导入导出
- [ ] 字段库和模板功能
- [ ] 国际化支持
- [ ] 暗黑模式
### 规划中 📋
- [ ] 版本管理和变更追踪
- [ ] 团队协作功能
- [ ] 接口上下线管理
- [ ] API 监控和分析
- [ ] AI 辅助测试
- [ ] 细粒度权限控制
查看完整路线图: [产品路线图](csap-apidoc-devtools/APIDOC开发工具产品路线图.md)
## 📖 文档
- [快速开始指南](QUICK_START.md) - 5分钟快速集成
- [注解参考手册](ANNOTATION_REFERENCE.md) - 完整的注解使用说明
- [网关聚合指南](GATEWAY-AGGREGATION.md) - 微服务网关聚合文档配置
- [常见问题 FAQ](FAQ.md) - 60+ 常见问题解答
- [架构设计](ARCHITECTURE.md) - 系统架构和设计原则
- [Postman 转换器](csap-apidoc-core/README-Postman.md) - Postman 集成
- [产品路线图](csap-apidoc-devtools/APIDOC开发工具产品路线图.md) - 未来规划
- [贡献指南](CONTRIBUTING.md) - 如何参与贡献
- [安全策略](SECURITY.md) - 安全相关说明
## 💡 示例项目
提供两个版本的示例项目,分别支持 Spring Boot 2.x 和 3.x:
- [示例项目集合](example/README.md) - 快速开始和版本对比
- [Spring Boot 2.x 示例](example/example-spring-boot2) - 基于 javax.servlet,适合 JDK 8/11
- [Spring Boot 3.x 示例](example/example-spring-boot3) - 基于 jakarta.servlet,适合 JDK 17+
- [注解使用指南](example/example-spring-boot3/ANNOTATIONS.md) - 正确的注解使用方式
- [策略对比](example/example-spring-boot3/STRATEGIES.md) - ANNOTATION vs SQLite vs YAML
- [高级示例](example/example-spring-boot3/src/main/java/ai/csap/example/controller/AdvancedController.java) - @ApiProperty 用法
## 🤝 贡献
我们欢迎所有形式的贡献!
### 如何贡献
1. Fork 本仓库
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启一个 Pull Request
### 贡献指南
- 遵循现有代码风格(详见 [代码风格指南](docs/development/code-style/CODE_STYLE_README.md))
- 提交前运行 `mvn checkstyle:check` 检查代码风格
- 添加必要的测试用例
- 更新相关文档
- 确保所有测试通过
## 🌟 致谢
感谢所有为这个项目做出贡献的开发者!
## 📄 许可证
本项目采用 [Apache License 2.0](LICENSE) 开源协议。
## 📮 联系我们
- **问题反馈**: [GitHub Issues](https://github.com/csap-ai/csap-apidoc/issues)
- **功能建议**: [GitHub Discussions](https://github.com/csap-ai/csap-apidoc/discussions)
- **邮件**: support@csap.ai
## 🔗 相关链接
- [官方网站](https://csap.ai)
- [在线文档](https://docs.csap.ai)
- [📚 文档中心](docs/README.md) ⭐ 完整文档索引
- [更新日志](CHANGELOG.md)
- [常见问题](docs/guides/FAQ.md)
- [快速入门](docs/guides/QUICK_START.md)
- [代码风格指南](docs/development/code-style/CODE_STYLE_README.md) - 开发必读
---
**如果这个项目对你有帮助,请给一个 ⭐️ Star 支持一下!**
Made with ❤️ by CSAP Team