mirror of
https://gitee.com/pnoker/iot-dc3.git
synced 2026-11-02 03:01:52 +08:00
pnoker
b674385904
Refresh architecture, development, operations, and quickstart docs. Update multi-language README files.
114 lines
5.4 KiB
Markdown
114 lines
5.4 KiB
Markdown
# API 文档
|
||
|
||
本页说明 IoT DC3 后端 OpenAPI / Swagger 文档的生成、访问、认证和导出方式。它补充 [测试](testing.md) 与根目录 `AGENTS.md`
|
||
中的工程规则。
|
||
|
||
平台在 WebFlux 栈上使用 `springdoc-openapi` `3.0.3`。REST 接口文档由代码注解生成，包括 `@Tag`、`@Operation`、`@Parameter` 和
|
||
`@Schema`，不维护独立的手写 API 规格文件。
|
||
|
||
## 架构
|
||
|
||
```text
|
||
+--------------------------------------------+
|
||
Browser | dc3-gateway (:8000) |
|
||
/swagger-ui.html ----> | Aggregated Swagger UI (service selector) |
|
||
| springdoc.swagger-ui.urls -> 4 centers |
|
||
+--------+-----------+-----------+-----------+
|
||
/v3/api-docs/auth | /manager | /data | /agentic
|
||
v v v
|
||
+------------+ +----------+ +----------+ +----------+
|
||
| auth :8300 | | mgr:8400 | | data:8500| |agentic |
|
||
| /auth/... | | /manager | | /data | | :8600 |
|
||
+------------+ +----------+ +----------+ +----------+
|
||
group=auth manager data agentic
|
||
```
|
||
|
||
## 分组方式
|
||
|
||
| 机制 | 说明 |
|
||
|------------|---------------------------------------------------------------------|
|
||
| Center 分组 | 每个业务模块提供自己的 `GroupedOpenApi` Bean，只扫描本模块 Controller 包 |
|
||
| 全局元信息 | `dc3-common-web` 中的 `SpringDocConfig` 提供 OpenAPI 标题、版本、联系人、许可证和安全方案 |
|
||
| Gateway 聚合 | Gateway 没有业务 Controller，通过 `springdoc.swagger-ui.urls` 聚合各中心服务文档 |
|
||
| Single 模式 | `dc3-center-single` 同时包含多个业务模块，因此 UI 中会出现多个分组 |
|
||
|
||
`SpringDocConfig` 和 `WebFluxSecurityConfig` 放在 `dc3-common-web` 的 auto-configuration 中，因为 Center
|
||
应用只扫描自身包路径。各业务模块的 `GroupedOpenApi` 放在本模块已扫描包下，由已有初始化逻辑加载。
|
||
|
||
## 访问入口
|
||
|
||
| 目标 | URL |
|
||
|-------------------|-------------------------------------------------|
|
||
| Gateway 聚合 UI | `http://<gateway>:8000/swagger-ui.html` |
|
||
| Auth Center 直连 | `http://<auth>:8300/auth/swagger-ui.html` |
|
||
| Manager Center 直连 | `http://<manager>:8400/manager/swagger-ui.html` |
|
||
| Data Center 直连 | `http://<data>:8500/data/swagger-ui.html` |
|
||
| Agentic Center 直连 | `http://<agentic>:8600/agentic/swagger-ui.html` |
|
||
| 单中心 JSON | `http://<center>:<port>/<svc>/v3/api-docs` |
|
||
|
||
各中心服务的 `spring.webflux.base-path` 会加到文档路径前，例如 `/auth/v3/api-docs`。Gateway 聚合路径 `/v3/api-docs/{svc}`
|
||
会隐藏这个差异，便于统一访问。
|
||
|
||
## Swagger UI 认证
|
||
|
||
除 `/auth/token/*` 外，多数接口需要通过 Gateway 认证头调用。开发环境中可按以下步骤操作：
|
||
|
||
1. 调用 `POST /api/v3/auth/token/salt`，请求体示例：`{"name":"dc3","tenant":"default"}`。
|
||
2. 计算 `md5(md5(password) + salt)`。
|
||
3. 调用 `POST /api/v3/auth/token/generate` 获取 token。
|
||
4. 在 Swagger UI 点击 **Authorize**，填写：
|
||
|
||
| Header | 示例 |
|
||
|-----------------|--------------------------------|
|
||
| `X-Auth-Tenant` | `default` |
|
||
| `X-Auth-Login` | `dc3` |
|
||
| `X-Auth-Token` | `{"salt":"...","token":"..."}` |
|
||
|
||
不要把真实 token、password、api key 写入文档、日志或 issue。
|
||
|
||
## 环境暴露规则
|
||
|
||
API 文档在 `dev`、`test`、`pre` 环境可用，生产环境关闭。共享配置 `application-web.yml` 的 `pro` profile 会设置：
|
||
|
||
```yaml
|
||
springdoc:
|
||
api-docs:
|
||
enabled: false
|
||
swagger-ui:
|
||
enabled: false
|
||
```
|
||
|
||
安全白名单允许文档路径本身访问；生产环境中 springdoc 端点不存在，因此不会暴露文档内容。
|
||
|
||
## 注解约定
|
||
|
||
- 注解文字使用英文，符合 `AGENTS.md` 对用户可见代码文本的要求。
|
||
- `@Operation` 摘要应遵循 CRUD 动词和结果基数约定：`add`、`delete`、`update`、`getXxx`、`listXxx`。
|
||
- 请求/响应 DTO 字段使用 `@Schema` 标明 `description`，必要时补充 `example` 和 `requiredMode = REQUIRED`。
|
||
- 不在 `@Schema` 示例中放 `apiKey`、`password`、`secret`、`token` 等敏感值。
|
||
- 接口统一返回 `R<T>` 响应封装，包含 `ok`、`code`、`message`、`data`。
|
||
|
||
## 导出 OpenAPI JSON
|
||
|
||
`make openapi` 会从运行中的开发或测试栈导出各中心服务的 OpenAPI JSON：
|
||
|
||
```bash
|
||
make openapi
|
||
```
|
||
|
||
可通过变量覆盖导出入口和输出目录：
|
||
|
||
```bash
|
||
make openapi OPENAPI_BASE=http://localhost:8000 OPENAPI_OUT=build/openapi
|
||
```
|
||
|
||
该命令适合生成离线契约快照或提供给客户端生成工具。
|
||
|
||
## 新增接口时的文档要求
|
||
|
||
1. Controller 类增加 `@Tag(name = "...", description = "...")`。
|
||
2. 方法增加 `@Operation(summary = "...", description = "...")`。
|
||
3. 路径参数、查询参数和请求体参数增加 `@Parameter`。
|
||
4. 请求/响应 DTO 字段增加 `@Schema`。
|
||
5. 新增业务模块时，补充 `GroupedOpenApi` Bean、Gateway 聚合配置和 Swagger UI 分组。
|