接口文档管理工具的价值
│
├── 集中管理
│   ├── 统一的文档存储位置
│   ├── 版本控制与历史追溯
│   └── 权限管理与团队协作
│
├── 在线调试
│   ├── 接口在线测试
│   ├── 参数快速验证
│   └── 响应结果即时查看
│
├── Mock数据
│   ├── 自动生成Mock数据
│   ├── 前后端并行开发
│   └── 减少联调时间
│
└── 团队协作
    ├── 文档实时同步
    ├── 评论与讨论
    └── 变更通知

工具选择决策树
│
├── 团队规模？
│   ├── 大型团队（20+人）→ YApi / Swagger
│   ├── 中型团队（5-20人）→ YApi / Apifox
│   └── 小型团队（<5人）→ ShowDoc / Apifox
│
├── 是否需要私有化部署？
│   ├── 是 → YApi / Swagger / ShowDoc
│   └── 否 → Apifox / Postman
│
└── 是否需要自动化测试？
    ├── 是 → Apifox / Postman / YApi
    └── 否 → ShowDoc / Swagger UI

YApi 功能架构
│
├── 项目管理
│   ├── 创建项目
│   ├── 项目权限设置
│   └── 项目分组
│
├── 接口管理
│   ├── 接口分类
│   ├── 接口定义（路径、方法、参数）
│   ├── 返回数据定义
│   └── 接口状态管理
│
├── Mock服务
│   ├── 自动生成Mock数据
│   ├── 自定义Mock脚本
│   └── Mock代理
│
├── 自动化测试
│   ├── 测试集合
│   ├── 自动化测试脚本
│   └── 定时测试任务
│
└── 数据导入导出
    ├── 导入Swagger/OpenAPI
    ├── 导出Postman
    └── 数据备份

项目文档结构示例
│
├── 项目说明
│   └── 项目介绍、技术栈、团队成员等
│
├── 变更日志
│   └── API变更记录、版本历史
│
├── 数据库设计
│   ├── 用户表（users）
│   ├── 订单表（orders）
│   └── 商品表（products）
│
└── 功能模块
    ├── 首页
    │   ├── 轮播图接口
    │   └── 推荐列表接口
    ├── 用户模块
    │   ├── 登录接口
    │   ├── 注册接口
    │   └── 个人信息接口
    └── 订单模块
        ├── 创建订单接口
        └── 订单列表接口

AI提示词编写流程
│
├── 第一步：明确需求格式
│   ├── 描述你想要什么类型的文档
│   ├── 说明文档的目标受众
│   └── 提供格式示例或要求
│
├── 第二步：提供详细资料
│   ├── 业务需求描述
│   ├── 技术要点说明
│   └── 特殊要求或约束
│
└── 第三步：迭代优化
    ├── 检查生成结果
    ├── 提出改进要求
    └── 多次对话优化

## 提示词模板示例

### 第一步：询问格式
"我想创建一个API接口文档，请问标准的API接口文档应该包含哪些内容？请提供格式示例。"

### 第二步：提供资料
"根据以下信息，帮我生成一个用户登录接口的文档：

**功能描述**：
- 用户通过用户名和密码登录系统
- 登录成功后返回token和用户基本信息

**技术要求**：
- 接口路径：/api/v1/auth/login
- 请求方式：POST
- 参数：username（用户名）、password（密码）
- 返回：token、userId、username、role

请按照标准的接口文档格式输出。"

### 第三步：优化调整
"请增加以下内容：
1. 添加错误码说明
2. 增加请求参数的校验规则
3. 提供更多的返回示例（成功、失败）"

项目文档结构
│
├── 01-项目说明
│   ├── 项目简介
│   ├── 技术栈说明
│   ├── 团队成员
│   └── 开发规范
│
├── 02-变更日志
│   ├── v1.0.0（2024-01-01）
│   ├── v1.1.0（2024-02-01）
│   └── WIP（进行中）
│
├── 03-数据库设计
│   ├── 用户表（users）
│   ├── 订单表（orders）
│   ├── 商品表（products）
│   └── 数据字典
│
├── 04-功能模块
│   ├── 首页模块
│   │   ├── 首页-轮播图接口
│   │   └── 首页-推荐列表接口
│   ├── 用户模块
│   │   ├── 用户-登录接口
│   │   ├── 用户-注册接口
│   │   └── 用户-个人信息接口
│   └── 订单模块
│       ├── 订单-创建接口
│       └── 订单-列表接口
│
└── 05-附录
    ├── 错误码说明
    ├── 通用参数说明
    └── 版本规划

文档命名规则
│
├── 项目说明
│   └── 直接命名为"项目说明"
│
├── 变更日志
│   ├── 标题：变更日志
│   ├── 标记：WIP（Work In Progress）表示进行中
│   └── 版本号格式：v1.0.0、v1.1.0
│
├── 数据库设计
│   ├── 选择类型：数据库
│   ├── 使用模板：数据库字典模板
│   └── 表名格式：英文小写、下划线分隔（user_profile）
│
└── 功能模块
    ├── 选择类型：API接口
    ├── 使用模板：API接口模板
    └── 命名格式：模块-功能（用户-登录接口）

# 接口文档工具与 API 设计实践

## 一、项目简介

### 1.1 项目名称
小闭环项目

### 1.2 项目背景
本项目是一个完整的前后端分离项目，旨在为用户提供...

### 1.3 核心功能
- 用户认证与授权
- 商品浏览与搜索
- 购物车管理
- 订单管理
- 支付集成

## 二、技术栈

### 2.1 前端技术栈
- 框架：Vue 3 / React 18
- 构建工具：Vite
- UI组件库：Element Plus / Ant Design
- 状态管理：Pinia / Redux Toolkit
- 请求库：Axios

### 2.2 后端技术栈
- 框架：NestJS
- 数据库：MySQL 8.0
- 缓存：Redis 7.0
- ORM：Prisma

### 2.3 开发工具
- 版本控制：Git
- 接口文档：YApi
- 代码规范：ESLint + Prettier

## 三、团队成员

| 姓名 | 角色 | 联系方式 |
|------|------|---------|
| 张三 | 前端开发 | zhangsan@example.com |
| 李四 | 后端开发 | lisi@example.com |
| 王五 | 测试工程师 | wangwu@example.com |

## 四、开发规范

### 4.1 代码规范
- 遵循 ESLint + Prettier 规范
- 使用 TypeScript 编写代码
- 组件命名：PascalCase
- 函数命名：camelCase

### 4.2 Git规范
- 分支命名：feature/xxx, bugfix/xxx, hotfix/xxx
- 提交信息：feat: 新增功能, fix: 修复bug

### 4.3 接口规范
- RESTful API设计
- 统一响应格式：{ code, message, data }
- 版本控制：/api/v1/

变更日志的价值
│
├── 版本追溯
│   ├── 记录每个版本的变更内容
│   ├── 方便问题定位
│   └── 历史版本对比
│
├── 团队协作
│   ├── 团队成员了解变更
│   ├── 减少沟通成本
│   └── 避免重复工作
│
└── 用户通知
    ├── 告知用户新功能
    ├── 说明变更影响
    └── 提供升级指南

# 变更日志

## [WIP] - 进行中

### 新增
- [用户模块] 用户登录接口
- [用户模块] 用户注册接口

### 修改
- [订单模块] 优化订单创建接口参数

### 待开发
- [支付模块] 支付接口集成

---

## [v1.1.0] - 2024-02-01

### 新增
- [商品模块] 商品搜索接口
- [商品模块] 商品分类接口

### 修改
- [用户模块] 用户信息接口增加头像字段

### 修复
- [订单模块] 修复订单列表分页问题

### 优化
- [通用] 优化接口响应速度

---

## [v1.0.0] - 2024-01-01

### 新增
- [用户模块] 用户登录接口
- [用户模块] 用户注册接口
- [商品模块] 商品列表接口
- [订单模块] 创建订单接口

### 技术栈
- 前端：Vue 3 + Vite
- 后端：NestJS + MySQL

# 使用 git-clog 工具自动生成
npm install -g git-clog

# 生成 Change Log
git-clog --template markdown > CHANGELOG.md

# 或使用 conventional-changelog
npm install -g conventional-changelog-cli
conventional-changelog -p angular -i CHANGELOG.md -s

前端开发者与数据库
│
├── 为什么前端需要了解数据库？
│   ├── 理解数据结构，更好地设计接口
│   ├── 了解数据关系，优化数据获取
│   └── 参与数据库设计，提升全栈能力
│
├── 前端参与的部分
│   ├── 数据字段定义（根据业务需求）
│   ├── 数据关系梳理
│   └── 接口参数设计
│
└── 后端负责的部分
    ├── 数据库选型
    ├── 表结构设计
    ├── 索引优化
    └── 性能调优

CREATE TABLE users (
  id INT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
  username VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名',
  password VARCHAR(255) NOT NULL COMMENT '密码（加密）',
  nickname VARCHAR(50) COMMENT '昵称',
  email VARCHAR(100) UNIQUE COMMENT '邮箱',
  phone VARCHAR(20) UNIQUE COMMENT '手机号',
  avatar VARCHAR(255) COMMENT '头像URL',
  role ENUM('user', 'admin') DEFAULT 'user' COMMENT '角色',
  status TINYINT DEFAULT 1 COMMENT '状态：1-正常，0-禁用',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  INDEX idx_username (username),
  INDEX idx_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

数据库设计注意事项
│
├── 必须字段
│   ├── id：主键，自增
│   ├── created_at：创建时间
│   └── updated_at：更新时间
│
├── 索引设计
│   ├── 主键索引（id）
│   ├── 唯一索引（username, email）
│   └── 普通索引（常用查询字段）
│
├── 字段规范
│   ├── 字段名：小写+下划线（user_name）
│   ├── 避免保留字（key, value, index）
│   └── 统一字符集（utf8mb4）
│
└── 安全考虑
    ├── 密码加密存储（bcrypt）
    ├── 敏感数据加密
    └── 软删除（deleted_at）

接口命名规范
│
├── 路径命名
│   ├── 使用小写字母
│   ├── 单词间用连字符（-）分隔
│   ├── 使用名词表示资源
│   └── 示例：/api/v1/user-profiles, /api/v1/order-items
│
├── 接口分类命名
│   ├── 格式：模块-功能
│   ├── 示例：用户-登录接口, 订单-创建接口
│   └── 便于文档组织和查找
│
└── 版本控制
    ├── 路径中包含版本号：/api/v1/
    ├── 重大变更升级版本：v1 → v2
    └── 保持向后兼容

RESTful API 设计原则
│
├── 资源导向
│   ├── URL表示资源
│   ├── 使用名词而非动词
│   └── 示例：/users, /orders
│
├── HTTP方法语义
│   ├── GET：获取资源
│   ├── POST：创建资源
│   ├── PUT：更新资源（完整）
│   ├── PATCH：更新资源（部分）
│   └── DELETE：删除资源
│
├── 状态码规范
│   ├── 200：成功
│   ├── 201：创建成功
│   ├── 400：请求参数错误
│   ├── 401：未授权
│   ├── 403：禁止访问
│   ├── 404：资源不存在
│   └── 500：服务器错误
│
└── 统一响应格式
    ├── code：业务状态码
    ├── message：提示信息
    └── data：返回数据

# 首页-轮播图接口

## 接口信息
- **接口名称**：首页轮播图
- **接口路径**：/home
- **请求方式**：GET
- **接口描述**：获取首页轮播图数据

## 请求参数
无

## 返回示例

### 成功响应
```json
{
  "code": 200,
  "message": "请求成功",
  "data": {
    "swipers": [
      {
        "id": 1,
        "image": "https://example.com/images/banner1.jpg",
        "title": "新品上市",
        "link": "/product/123"
      },
      {
        "id": 2,
        "image": "https://example.com/images/banner2.jpg",
        "title": "限时优惠",
        "link": "/sale"
      }
    ]
  }
}

{
  "code": 500,
  "message": "服务端异常",
  "data": null
}

**用户登录接口示例**：

```markdown
# 用户-登录接口

## 接口信息
- **接口名称**：用户登录
- **接口路径**：/api/v1/auth/login
- **请求方式**：POST
- **接口描述**：用户通过用户名和密码登录系统

## 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名（4-20字符） |
| password | string | 是 | 密码（6-20字符） |

## 请求示例
```json
{
  "username": "testuser",
  "password": "Test@123"
}

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "testuser",
      "nickname": "测试用户",
      "avatar": "https://example.com/avatar.jpg",
      "role": "user"
    }
  }
}

{
  "code": 401,
  "message": "用户名或密码错误",
  "data": null
}

---



### 5.4 接口设计实战流程 

**接口设计步骤**：

**首页模块接口设计示例**：

**接口数据结构设计**：

```typescript
// 首页接口返回数据结构
interface HomeData {
  swipers: Swiper[]       // 轮播图
  categories: Category[]  // 项目分类
  projects: Project[]     // 推荐项目
  courses: Course[]       // 课程展示
  partners: Partner[]     // 合作伙伴
}

// 轮播图
interface Swiper {
  id: number
  image: string    // 图片URL
  title: string    // 标题
  link: string     // 跳转链接
}

// 项目
interface Project {
  id: number
  name: string     // 项目名称
  link: string     // 项目链接
}

// 课程
interface Course {
  id: number
  image: string       // 图片
  title: string       // 标题
  description: string // 描述
  link: string        // 链接
}

// 合作伙伴
interface Partner {
  id: number
  image: string   // 图片
  name: string    // 名称
}

文档维护规范
│
├── 及时更新
│   ├── 接口变更时立即更新文档
│   ├── 避免文档与实际接口不一致
│   └── 重要变更需通知团队
│
├── 版本管理
│   ├── 每次更新记录变更内容
│   ├── 保留历史版本
│   └── 标注更新时间和责任人
│
├── 定期审核
│   ├── 定期检查文档完整性
│   ├── 删除废弃接口文档
│   └── 补充缺失的说明
│
└── 团队协作
    ├── 文档评审机制
    ├── 变更通知机制
    └── 权限管理