# apipost-api

**Repository Path**: alwarse/apipost-api

## Basic Information

- **Project Name**: apipost-api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-10
- **Last Updated**: 2025-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# APIPost接口文档生成器

## 项目说明
本项目基于APIPost导出的JSON文件，按照指定的Word模板格式，自动生成标准化的接口文档。

## 实现方案

### 技术栈
- Python 3.12.9
- python-docx：用于处理Word文档
- json：解析APIPost导出的JSON数据

### 核心功能模块

#### 1. JSON数据解析模块 (json_parser.py)
- 解析APIPost导出的JSON文件
- 提取接口信息：名称、方法、URL、描述等
- 提取请求参数：headers、query参数、body参数等
- 提取响应参数：响应示例、参数结构等

#### 2. Word模板解析模块 (template_parser.py)
- 分析模板文档结构
- 提取样式信息
- 识别占位符和格式要求

#### 3. 文档生成模块 (doc_generator.py)
- 根据模板样式创建新文档
- 按照模板格式填充接口数据
- 生成完整的接口文档

#### 4. 主程序 (main.py)
- 统筹各模块协作
- 处理文件输入输出
- 错误处理和日志记录

### 模板结构分析
根据template-word.docx中的2.1.1.1示例接口章节，接口文档包含以下部分：

1. **接口信息**
   - 接口名称
   - 请求方法
   - 请求URL
   - 接口描述

2. **请求参数说明**
   - Header参数表格
   - Query参数表格
   - Body参数表格（包含JSON格式示例）

3. **响应参数说明**
   - 响应头示例
   - 响应体示例（JSON格式）
   - 参数详细说明表格

### 实现进度

- [x] 项目初始化和依赖安装
- [x] JSON数据解析模块开发
- [x] Word模板分析
- [x] 文档生成模块开发
- [x] 主程序集成
- [x] 配置文件支持
- [x] 测试和优化
- [x] 文档完善

### 🎉 项目完成状态

✅ **项目已全部完成！** 

**实现的功能特性：**
1. ✅ **完整的JSON解析**：支持APIPost导出的所有字段
2. ✅ **专业的Word文档生成**：基于模板的样式保持
3. ✅ **灵活的配置系统**：通过config.ini自定义设置
4. ✅ **完整的接口文档结构**：信息表、参数表、响应示例
5. ✅ **标准化表格格式**：完全符合模板要求的表格结构
6. ✅ **嵌套数据支持**：自动展开对象和数组的完整结构
7. ✅ **代码格式化**：JSON自动美化显示
8. ✅ **批处理脚本**：一键运行支持
9. ✅ **错误处理**：完善的异常处理机制

**表格格式特点：**
- ✅ **请求参数表格**：4列格式（参数名、参数类型、是否必填、描述），可选5列（+示例）
- ✅ **响应参数表格**：5列格式（参数名、参数类型、是否必填、父节点、描述），可选6列（+示例）
- ✅ **灵活的示例展示**：可通过配置控制是否在表格中显示示例列
- ✅ **嵌套结构支持**：自动展开对象下的所有子属性
- ✅ **数组类型支持**：正确处理数组中的对象结构
- ✅ **必填字段识别**：基于JSON Schema的required字段准确标识

**测试验证：**
- ✅ 成功解析 `export-demo1.json` 中的接口数据
- ✅ 生成的Word文档格式规范、内容完整
- ✅ 支持Header、Query、Body参数解析
- ✅ 响应参数结构完整展示
- ✅ JSON示例格式化显示正常

## 使用方法

### 方法一：直接运行Python脚本
```bash
# 安装依赖
pip install python-docx

# 运行程序
python main.py
```

### 方法二：使用批处理脚本（Windows）
```bash
# 双击运行或在命令行执行
run.bat
```

### 自定义输入文件
如果要处理其他APIPost导出的JSON文件：
1. 将JSON文件放入 `input/` 目录
2. 修改 `config.ini` 中的 `input_file` 配置指向新文件
3. 运行程序

### 配置选项说明

项目支持通过 `config.ini` 文件进行灵活配置：

#### [files] 文件路径配置
- `input_file`: 输入JSON文件路径
- `template_file`: Word模板文件路径  
- `output_dir`: 输出目录路径

#### [document] 文档格式配置
- `include_timestamp`: 是否在文档中包含生成时间戳
- `add_page_break`: 是否为每个接口添加分页符
- `default_font_size`: 默认字体大小
- `include_request_body_example`: 是否包含请求体示例（默认：false）
- `include_response_example`: 是否包含响应示例（默认：false）
- `show_example_column`: 是否在参数表格中显示示例列（默认：false）

#### [format] 格式化配置
- `section_start`: 章节编号起始值
- `format_json`: 是否格式化JSON输出
- `json_indent`: JSON缩进空格数

**使用提示：**
- 将 `include_request_body_example` 设为 `true` 可在文档中显示完整的请求体JSON示例
- 将 `include_response_example` 设为 `true` 可在文档中显示完整的响应JSON示例
- 将 `show_example_column` 设为 `true` 可在Header、Query、Body、响应参数表格中添加"示例"列
- 前两个选项控制JSON示例块的显示，第三个选项控制表格中示例列的显示
- 这些选项默认为 `false`，以保持文档简洁

## 输入输出

- **输入**：`input/export-demo1.json` - APIPost导出的JSON文件
- **模板**：`template/template-word.docx` - Word文档模板
- **输出**：`output/` - 生成的接口文档（.docx格式）

## 功能特点

1. **自动解析APIPost导出的JSON文件**
   - 支持完整的API信息提取
   - 智能识别请求参数（Header、Query、Body）
   - 自动解析响应结构和示例

2. **专业的Word文档格式**
   - 基于Word模板的样式保持
   - 规范的表格格式
   - 代码块语法高亮
   - 自动章节编号

3. **完整的接口文档结构**
   - 接口基本信息表
   - 请求参数详细说明
   - 响应参数结构分析
   - JSON示例格式化显示

## 详细使用说明

#### 1. 环境准备
```bash
# 确保Python版本为3.12.9
python --version

# 安装依赖
pip install python-docx
```

#### 2. 文件准备
- 将APIPost导出的JSON文件放入 `input/` 目录
- 确保Word模板文件 `template-word.docx` 在 `template/` 目录中

#### 3. 运行程序
```bash
python main.py
```

#### 4. 查看结果
生成的文档将保存在 `output/` 目录下，文件名格式为：
`项目名称_接口文档_时间戳.docx`

### 支持的接口特性

- ✅ HTTP方法：GET、POST、PUT、DELETE等
- ✅ 请求参数：Header、Query、Body（JSON/Form）
- ✅ 认证方式：Bearer Token、Basic Auth等
- ✅ 响应格式：JSON格式的响应数据
- ✅ 参数验证：必填字段、数据类型、示例值
- ✅ 错误响应：多种响应状态码

### 最终项目结构

```
apipost-api/
├── README.md                    # 项目说明文档 ✅
├── requirements.txt             # Python依赖包 ✅
├── config.ini                   # 配置文件 ✅
├── main.py                     # 主程序入口 ✅
├── run.bat                     # Windows批处理脚本 ✅
├── src/                        # 源代码目录
│   ├── json_parser.py          # JSON解析模块 ✅
│   ├── doc_generator.py        # Word文档生成模块 ✅
│   └── config.py               # 配置文件读取模块 ✅
├── input/                      # 输入文件目录
│   └── export-demo1.json       # APIPost导出的JSON文件 ✅
├── template/                   # 模板文件目录
│   └── template-word.docx      # Word文档模板 ✅
└── output/                     # 输出文件目录
    └── *.docx                  # 生成的接口文档 ✅
```

### 扩展说明

本项目已实现完整的APIPost接口文档自动生成功能，支持：
- 多种请求方法（GET/POST/PUT/DELETE等）
- 复杂的参数结构（嵌套对象、数组等）
- 多种认证方式
- 完整的响应结构分析
- 灵活的配置选项

可根据需要进一步扩展功能，如：
- 支持Swagger/OpenAPI格式导出
- 添加接口测试用例生成
- 支持Markdown格式输出
- 集成CI/CD自动化流程