# api2word

**Repository Path**: honley/api2word

## Basic Information

- **Project Name**: api2word
- **Description**: 本工具用于将 APIFox 或 OpenAPI 导出的 JSON 格式接口文档转换为 Word 文档格式。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-24
- **Last Updated**: 2025-11-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 📚 接口文档生成工具说明

## 🆕 更新说明

工具已升级为统一接口文档生成器，支持多种JSON格式的自动识别和处理，包括APIFox和OpenAPI 3.0+格式。

## 📖 概述

本工具用于将 APIFox 或 OpenAPI 导出的 JSON 格式接口文档转换为 Word 文档格式。

支持的格式：
1. APIFox JSON 格式
2. OpenAPI 3.0+ JSON 格式

支持的生成模式：
1. 合并模式(a)：将所有接口信息合并到一个 Word 文档中
2. 独立模式(d)：为每个接口生成一个独立的 Word 文档

## 📁 工具文件

- `doc_generator.py` - 统一接口文档生成器（推荐使用）
- `apifox_cli.py` - APIFox格式专用命令行工具
- `openapi_cli.py` - OpenAPI格式专用命令行工具（基于纯JSON解析）
- `openapi3_cli.py` - OpenAPI 3.0+格式专用命令行工具（基于 python-openapi3 库，推荐）
- `doc_utils.py` - 公共工具函数模块

## 🔧 安装依赖

在运行工具前，请确保已安装所需依赖：

```bash
pip install python-docx
```

或者使用项目中的 requirements.txt：

```bash
pip install -r requirements.txt
```

这将安装以下依赖：
- python-docx>=0.8.11
- pandas>=1.3.0
- openpyxl>=3.0.0
- openapi3>=1.8.2

## 🚀 使用方法

### 基本语法

```bash
# 使用统一生成器（推荐，自动识别格式）
python doc_generator.py <input_file> [--mode {a,d}] [--output OUTPUT] [--color HEADER_COLOR]

# 或者使用专用工具
python apifox_cli.py <input_file> [--mode {a,d}] [--output OUTPUT] [--color HEADER_COLOR]
python openapi3_cli.py <input_file>  [--mode {a,d}] [--output OUTPUT] [--color HEADER_COLOR]
```

### 参数说明

| 参数 | 说明 | 必需 |
|------|------|------|
| input_file | JSON格式的接口文档文件路径 | 是 |
| --mode | 生成模式：a（所有接口在一个文档）或 d（每个接口一个单独的文档） | 否，默认为 a |
| --output | 输出文件或目录路径 | 否，默认为当前目录 |
| --color | 标题单元格背景颜色（十六进制格式，如：CCCCCC） | 否，默认无背景色 |

### 使用示例

#### 1. 使用统一生成器（推荐）

自动识别JSON格式并生成文档：

```bash
# 处理APIFox格式（所有接口在一个文档）
python doc_generator.py demo_api.apifox.json

# 处理APIFox格式（每个接口一个单独的文档）
python doc_generator.py demo_api.apifox.json --mode d --output my_output_dir

# 处理OpenAPI格式
python doc_generator.py test_api/对比分析.openapi.json
```

#### 2. 生成文档并指定输出文件名

```bash
python doc_generator.py demo_api.apifox.json --output my_document.docx
python doc_generator.py demo_api.apifox.json --mode d --output my_output_dir
python doc_generator.py test_api/对比分析.openapi.json --output openapi_document.docx
```

#### 3. 生成带颜色标题的文档

```bash
python doc_generator.py demo_api.apifox.json --color F2F2F2
python doc_generator.py demo_api.apifox.json --mode d --color F2F2F2 --output my_output_dir
```

这将生成带有浅蓝色标题背景的文档，使非内容性标题更加突出。

#### 4. 使用专用工具处理APIFox格式

```bash
# 生成合并文档（默认）
python apifox_cli.py demo_api.apifox.json

# 生成独立文档
python apifox_cli.py demo_api.apifox.json --mode a

# 生成独立文档并指定输出目录
python apifox_cli.py demo_api.apifox.json --mode a --output my_output_dir
```

#### 5. 使用专用工具处理OpenAPI格式

```bash
# 使用基于openapi3库的解析器（推荐）
python openapi3_cli.py test_api/对比分析.openapi.json --output openapi_document.docx

# 使用基于纯JSON解析的版本
python openapi_cli.py test_api/对比分析.openapi.json --output openapi_document.docx
```

## 📄 输出格式

生成的 Word 文档包含以下信息：

1. 接口标题（包含序号、名称、请求方法和路径）
2. 功能描述
3. 接口方式和地址
4. 请求字段表（包含名称、位置、类型、必选性和说明）
5. 响应参数表（包含完整层级结构的名称、类型、必选性、约束和中文描述）
6. 错误响应表（包含状态码、说明和响应体）
7. 请求示例（格式化后的 JSON 数据）
8. 返回示例（格式化后的 JSON 数据）

### 响应参数深度解析

工具会对响应参数进行深度解析，不仅能解析顶层字段，还能递归解析嵌套的对象和数组类型字段。对于每个字段，会显示：

- 完整的字段路径（如 `data.items[].name`）
- 字段类型（如 string, integer, object, array 等）
- 是否必选
- 字段描述信息

### 标题单元格着色

使用`--color`参数可以为以下标题单元格添加背景色并自动加粗：

⚠️ 推荐使用 F2F2F2

- 接口描述（第一列固定显示"接口描述"并加粗着色，第二列显示接口功能描述内容）
- 接口方式
- 接口地址
- 请求字段
- 响应参数
- 错误响应
- 请求示例
- 返回示例

这使得文档结构更加清晰，标题更加突出，提高文档的可读性。

## 📝 文件命名规则

在独立文档模式下，每个接口文档的命名规则为：
```
序号_接口名称_请求方法_路径.docx
```

例如：
```
1_用户登录_POST_api_login.docx
```

> 注意：文件命名规则仅适用于APIFox格式的独立文档模式

## ⚠️ 注意事项

1. 工具会自动处理文件名中的非法字符
2. 如果输出目录不存在，工具会自动创建
3. 生成的文档使用宋体作为中文字体，确保中文正确显示
4. 工具保留了原有的向后兼容脚本，可以继续使用
5. 响应参数表会显示完整的层级结构，包括嵌套对象和数组中的字段
6. 标题单元格背景色参数接受十六进制颜色值，如：CCCCCC、FF000等
7. 当使用颜色参数时，标题单元格会自动加粗显示
8. 统一生成器(doc_generator.py)会自动识别JSON格式并选择合适的处理方式
9. 对于OpenAPI格式，推荐使用openapi3_cli.py（基于openapi3库）以获得更好的解析准确性