93 lines
2.1 KiB
Markdown
93 lines
2.1 KiB
Markdown
# API 接口文档模板
|
||
|
||
> 复制此文件，命名为 {module}-api.md，记录该模块对外暴露的 REST 接口。
|
||
|
||
---
|
||
|
||
## 模块信息
|
||
- **模块名**：{模块中文名} / {module}
|
||
- **Controller**：`{功能}RestController`
|
||
- **@eo.groupName**：`{一级模块}.{二级模块}`
|
||
- **@eo.path（base）**：`/{模块}/{资源}`
|
||
- **文件路径**：`other-adapter/src/.../adapter/app/{模块}/{功能}RestController.java`
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. {接口名称}
|
||
|
||
```java
|
||
/**
|
||
* {接口说明}.
|
||
*
|
||
* @eo.name {接口名称}
|
||
* @eo.url {子路径，GET无子路径时留空}
|
||
* @eo.method get
|
||
* @eo.request-type formdata
|
||
*/
|
||
@GetMapping("/{sub-path}")
|
||
public {返回CO或DTO} {methodName}({QryCmd} cmd) {
|
||
return {service}.{method}(cmd);
|
||
}
|
||
```
|
||
|
||
**请求参数（QryCmd 字段）**：
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| userId | Long | 否 | 目标用户ID（不传则取当前登录用户） |
|
||
|
||
**响应（CO 字段）**：
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| userId | Long | 用户ID |
|
||
| nickname | String | 昵称 |
|
||
|
||
---
|
||
|
||
### 2. {写操作接口名称}
|
||
|
||
```java
|
||
/**
|
||
* {接口说明}.
|
||
*
|
||
* @eo.name {接口名称}
|
||
* @eo.url /{sub-path}
|
||
* @eo.method post
|
||
* @eo.request-type json
|
||
*/
|
||
@PostMapping("/{sub-path}")
|
||
public {返回CO} {methodName}(@RequestBody @Validated {Cmd} cmd) {
|
||
return {service}.{method}(cmd);
|
||
}
|
||
```
|
||
|
||
**请求体（Cmd 字段）**：
|
||
| 字段 | 类型 | 必填 | 校验 | 说明 |
|
||
|------|------|------|------|------|
|
||
| activityId | Long | 是 | @NotNull | 活动ID |
|
||
| drawCount | Integer | 否 | @Min(1) @Max(10) | 抽奖次数 |
|
||
|
||
**响应（CO 字段）**：
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| prizeId | Long | 奖品ID |
|
||
| prizeName | String | 奖品名称 |
|
||
|
||
---
|
||
|
||
## 枚举值说明
|
||
|
||
| 枚举类 | 值 | 说明 |
|
||
|-------|----|------|
|
||
| StatusEnum | 0 | 正常 |
|
||
| StatusEnum | 1 | 禁用 |
|
||
|
||
---
|
||
|
||
## 关联文件
|
||
- Service 接口：`other-client/src/.../app/service/{模块}/{功能}Service.java`
|
||
- Cmd：`other-client/src/.../app/dto/cmd/{模块}/`
|
||
- CO：`other-client/src/.../app/dto/clientobject/{模块}/`
|
||
- CmdExe：`other-application/src/.../app/command/{模块}/`
|