88e030b7
 王彪总
init project
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
# java110-doc 模块技术文档
## 项目概述
`java110-doc` 是 HC 微服务社区项目的 API 文档生成模块，基于自定义注解实现智能化的 API 文档管理和展示功能。该模块为整个微服务架构提供统一的接口文档管理解决方案。
## 模块说明
- **模块类型**: API 文档生成与管理
- **技术栈**: Spring Boot + 自定义注解 + 前端静态页面
- **核心功能**: 通过注解自动生成 API 文档，提供可视化文档界面
## 技术架构
### 核心组件
1. **注解系统** (11个核心注解)
- `@Java110ApiDoc`: 项目级文档配置
- `@Java110CmdDoc`: 接口命令文档
- `@Java110ParamsDoc`: 请求参数文档
- `@Java110ResponseDoc`: 响应参数文档
- `@Java110ExampleDoc`: 请求/响应示例
2. **控制器层**
- `DocController`: 文档数据接口控制器
3. **数据实体层**
- `ApiDocDto`: API 文档数据传输对象
- `CmdDocDto`: 命令文档数据传输对象
- `RequestMappingsDocDto`: 请求映射文档数据传输对象
4. **注册器层**
- 注解发现与注册机制
- 文档发布管理
5. **前端界面**
- `doc-ui.html`: 文档展示主页面
- 静态资源 (CSS/JS/Mock数据)
## 目录结构
```
java110-doc/
├── src/main/java/com/java110/doc/
│ ├── annotation/ # 注解定义 (11个核心注解)
│ ├── controller/ # 控制器层
│ ├── entity/ # 数据实体层
│ └── registrar/ # 注解注册器
├── src/main/resources/static/
│ ├── css/ # 样式文件
│ ├── js/ # JavaScript文件
│ ├── mock/ # 模拟数据
│ └── doc-ui.html # 文档界面
└── pom.xml # Maven配置
```
## 核心功能详解
### 1. 项目级文档配置
```java
@Java110ApiDoc(
title = "HC小区管理系统api接口文档",
description = "HC小区管理系统api接口文档",
company="Java110工作室",
version = "v1.4"
)
```
### 2. 微服务路由映射
```java
@Java110RequestMappingsDoc(
mappingsDocs = {
@Java110RequestMappingDoc(name="用户中心", resource="user", url="http://service-user/userDoc", seq=1),
@Java110RequestMappingDoc(name="账户中心", resource="acct", url="http://service-acct/acctDoc", seq=2)
}
)
```
### 3. 接口命令文档
```java
@Java110CmdDoc(
title = "用户登录",
description = "登录功能主要用于员工或管理员登录使用",
httpMethod = "post",
url = "/app/login.pcUserLogin",
resource = "user",
author = "吴学文"
)
```
### 4. 参数文档系统
- **请求参数**: `@Java110ParamsDoc` + `@Java110ParamDoc`
- **响应参数**: `@Java110ResponseDoc` + `@Java110ParamDoc`
- **示例数据**: `@Java110ExampleDoc`
## 依赖配置
```xml
<dependencies>
<dependency>
<groupId>com.java110</groupId>
<artifactId>java110-core</artifactId>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
```
## 使用指南
### 1. 文档访问
访问地址: `http://ip:port/doc-ui.html`
示例: `http://127.0.0.1:8008/doc-ui.html`
### 2. 注解使用流程
1. **项目配置**: 在入口类使用 `@Java110ApiDoc`
2. **服务映射**: 配置 `@Java110RequestMappingsDoc`
3. **接口定义**: 为每个接口添加 `@Java110CmdDoc`
4. **参数说明**: 添加请求和响应参数注解
5. **示例配置**: 提供请求响应示例
### 3. Nginx 配置示例
```nginx
server {
listen 80;
server_name apidoc.homecommunity.cn;
location / {
proxy_pass http://dev.api.java110.com:8008/doc-ui.html;
}
location /js {
proxy_pass http://dev.api.java110.com:8008;
}
location /css {
proxy_pass http://dev.api.java110.com:8008;
}
location /doc {
add_header 'Access-Control-Allow-Origin' '*';
proxy_pass http://dev.api.java110.com:8088;
}
}
```
## 开发规范
1. **注解完整性**: 每个接口必须包含完整的注解配置
2. **参数说明**: 所有参数必须明确类型、长度、说明
3. **示例数据**: 提供真实的请求响应示例
4. **版本管理**: 及时更新文档版本信息
## 优势特点
- **自动化**: 基于注解自动生成文档，减少手动维护
- **标准化**: 统一的文档格式和规范
- **可视化**: 友好的Web界面展示
- **集成化**: 与微服务架构深度集成
- **可扩展**: 支持多服务、多版本的文档管理
## 注意事项
1. 确保所有微服务正确配置文档注解
2. 文档服务需要能够访问各微服务的文档接口
3. 生产环境建议通过Nginx进行反向代理
4. 定期检查文档与实际接口的一致性
---
|
