hookehuyr

docs: 将OpenAPI文档目录从docs/openAPI重命名为docs/api-specs

- 更新所有相关文档中的路径引用
- 同步更新模板文件名从openAPI-template.md为api-specs-template.md
- 保持API生成器功能不变,仅修改目录命名
......@@ -97,7 +97,7 @@ yarn api:diff # 对比 API 变更
**使用流程**:
1. 在 `docs/openAPI/模块名/接口名.md` 创建 OpenAPI 文档
1. 在 `docs/api-specs/模块名/接口名.md` 创建 OpenAPI 文档
2. 运行 `yarn api:generate` 自动生成 `src/api/模块名.js`
3. 导入并使用生成的 API 函数
......
......@@ -8,11 +8,11 @@
```bash
# 创建模块目录
mkdir -p docs/openAPI/yourModule
mkdir -p docs/api-specs/yourModule
# 复制模板
cp .claude/custom_skills/api-generator/templates/openAPI-template.md \
docs/openAPI/yourModule/yourApiName.md
cp .claude/custom_skills/api-generator/templates/api-specs-template.md \
docs/api-specs/yourModule/yourApiName.md
```
### 2. 编辑 OpenAPI 文档
......@@ -41,7 +41,7 @@ if (code === 1) {
## 目录结构
```
docs/openAPI/
docs/api-specs/
├── example/ # 示例模块
│ └── getExample.md # 示例接口
├── user/ # 用户模块(你的模块)
......@@ -66,7 +66,7 @@ docs/openAPI/
yarn api:generate
# 对比 API 变更
yarn api:diff docs/openAPI/user/ docs/openAPI/user-new/
yarn api:diff docs/api-specs/user/ docs/api-specs/user-new/
# 查看完整文档
cat .claude/custom_skills/api-generator/skill.md
......@@ -171,7 +171,7 @@ responses:
## 生成的代码示例
### 输入:`docs/openAPI/user/getUserInfo.md`
### 输入:`docs/api-specs/user/getUserInfo.md`
```yaml
paths:
......
......@@ -32,7 +32,7 @@ mlaj/
│ ├── generateApiFromOpenAPI.cjs # API 生成
│ └── apiDiff.cjs # API 对比
├── templates/
│ └── openAPI-template.md # 文档模板
│ └── api-specs-template.md # 文档模板
└── setup/
└── install.sh # 安装脚本
```
......@@ -73,7 +73,7 @@ yarn api:generate
# ✅ 正常工作
# 对比 API 变更
yarn api:diff docs/openAPI/example/ docs/openAPI/example/
yarn api:diff docs/api-specs/example/ docs/api-specs/example/
# ✅ 正常工作
```
......
......@@ -135,12 +135,12 @@ docs/tools/SKILLS_GUIDE.md
- 路径: `/.claude/custom_skills/api-generator/skill.md`
- 内容: 完整的 Skill 文档(500+ 行)
5. **docs/openAPI/README.md** - OpenAPI 目录说明
- 路径: `/docs/openAPI/README.md`
5. **docs/api-specs/README.md** - OpenAPI 目录说明
- 路径: `/docs/api-specs/README.md`
- 内容: 目录结构、使用方法、命令速查
6. **openAPI-template.md** - 文档模板
- 路径: `/.claude/custom_skills/api-generator/templates/openAPI-template.md`
6. **api-specs-template.md** - 文档模板
- 路径: `/.claude/custom_skills/api-generator/templates/api-specs-template.md`
- 内容: OpenAPI 文档编写模板
## 🎯 用户如何使用
......@@ -165,9 +165,9 @@ docs/tools/SKILLS_GUIDE.md
```bash
# 生成第一个 API
mkdir -p docs/openAPI/user
cp .claude/custom_skills/api-generator/templates/openAPI-template.md \
docs/openAPI/user/getUserInfo.md
mkdir -p docs/api-specs/user
cp .claude/custom_skills/api-generator/templates/api-specs-template.md \
docs/api-specs/user/getUserInfo.md
# 编辑文档后生成代码
yarn api:generate
......@@ -182,7 +182,7 @@ docs/tools/SKILLS_GUIDE.md
├─> 阅读 API_GENERATOR_GUIDE → 学习使用方法
└─> 查看 docs/openAPI/README → 了解 OpenAPI 规范
└─> 查看 docs/api-specs/README → 了解 OpenAPI 规范
```
## 📈 文档质量指标
......
......@@ -9,7 +9,7 @@
### 1. 核心功能移植
-**API 生成脚本** - `generateApiFromOpenAPI.cjs`
- 扫描 `docs/openAPI/` 目录
- 扫描 `docs/api-specs/` 目录
- 解析 OpenAPI 3.0.1 YAML 文档
- 生成标准的 API 调用代码(常量 + 函数 + JSDoc)
- 自动备份和变更检测
......@@ -31,7 +31,7 @@
│ ├── generateApiFromOpenAPI.cjs # API 生成脚本
│ └── apiDiff.cjs # API 对比脚本
├── templates/
│ └── openAPI-template.md # OpenAPI 文档模板
│ └── api-specs-template.md # OpenAPI 文档模板
└── setup/
└── install.sh # 跨项目安装脚本
```
......@@ -42,15 +42,15 @@
-**npm scripts**
- `api:generate` - 生成 API 代码
- `api:diff` - 对比 API 变更
-**示例文档**`docs/openAPI/example/getExample.md`
-**使用指南**`docs/openAPI/README.md`
-**示例文档**`docs/api-specs/example/getExample.md`
-**使用指南**`docs/api-specs/README.md`
-**完整文档**`docs/tools/API_GENERATOR_GUIDE.md`
### 4. 文档更新
- ✅ 创建 `docs/tools/API_GENERATOR_GUIDE.md` - 完整使用指南
- ✅ 更新 `docs/tools/SKILLS_GUIDE.md` - 添加 API Generator 入口
- ✅ 创建 `docs/openAPI/README.md` - OpenAPI 目录说明
- ✅ 创建 `docs/api-specs/README.md` - OpenAPI 目录说明
- ✅ 创建示例文档和模板
## 🎯 功能特性
......@@ -84,9 +84,9 @@
1. **创建文档**
```bash
mkdir -p docs/openAPI/user
cp .claude/custom_skills/api-generator/templates/openAPI-template.md \
docs/openAPI/user/getUserInfo.md
mkdir -p docs/api-specs/user
cp .claude/custom_skills/api-generator/templates/api-specs-template.md \
docs/api-specs/user/getUserInfo.md
```
2. **编辑 OpenAPI 文档**
......@@ -178,8 +178,8 @@ bash .claude/custom_skills/api-generator/setup/install.sh
- **完整使用指南**[docs/tools/API_GENERATOR_GUIDE.md](../../docs/tools/API_GENERATOR_GUIDE.md)
- **Skill 主文档**[.claude/custom_skills/api-generator/skill.md](../../.claude/custom_skills/api-generator/skill.md)
- **OpenAPI 目录说明**[docs/openAPI/README.md](../../docs/openAPI/README.md)
- **OpenAPI 文档模板**[.claude/custom_skills/api-generator/templates/openAPI-template.md](../../.claude/custom_skills/api-generator/templates/openAPI-template.md)
- **OpenAPI 目录说明**[docs/api-specs/README.md](../../docs/api-specs/README.md)
- **OpenAPI 文档模板**[.claude/custom_skills/api-generator/templates/api-specs-template.md](../../.claude/custom_skills/api-generator/templates/api-specs-template.md)
## ✨ 优势与改进
......
......@@ -14,11 +14,11 @@ yarn add -D js-yaml
```bash
# 1. 创建模块目录
mkdir -p docs/openAPI/user
mkdir -p docs/api-specs/user
# 2. 复制模板
cp .claude/custom_skills/api-generator/templates/openAPI-template.md \
docs/openAPI/user/getUserInfo.md
cp .claude/custom_skills/api-generator/templates/api-specs-template.md \
docs/api-specs/user/getUserInfo.md
# 3. 编辑文档(按照模板填写)
......@@ -64,7 +64,7 @@ if (code === 1) {
## 📁 目录结构
```
docs/openAPI/ # OpenAPI 文档目录
docs/api-specs/ # OpenAPI 文档目录
├── example/ # 示例模块
│ └── getExample.md # 示例接口
├── user/ # 用户模块
......@@ -78,7 +78,7 @@ docs/openAPI/ # OpenAPI 文档目录
│ ├── generateApiFromOpenAPI.cjs
│ └── apiDiff.cjs
├── templates/ # 文档模板
│ └── openAPI-template.md
│ └── api-specs-template.md
└── setup/ # 安装脚本
└── install.sh
```
......@@ -173,10 +173,10 @@ node .claude/custom_skills/api-generator/scripts/generateApiFromOpenAPI.cjs
```bash
# 对比两个目录
yarn api:diff docs/openAPI/user/ docs/openAPI/user-new/
yarn api:diff docs/api-specs/user/ docs/api-specs/user-new/
# 对比两个文件
yarn api:diff docs/openAPI/user/getInfo.md docs/openAPI/user/getInfo-v2.md
yarn api:diff docs/api-specs/user/getInfo.md docs/api-specs/user/getInfo-v2.md
# 输出 JSON 格式
API_DIFF_FORMAT=json yarn api:diff ...
......@@ -261,7 +261,7 @@ yarn api:generate
### 3. 版本管理
- `docs/openAPI/` 纳入版本控制
- `docs/api-specs/` 纳入版本控制
- `src/api/*.js` 也纳入版本控制
- 保留变更历史,方便回滚
......