#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
将 Swagger JSON 文件转换为 Word 格式的接口文档
"""import json
from docx import Document
from docx.shared import Pt, RGBColor, Inches
from docx.enum.text import WD_PARAGRAPH_ALIGNMENTdef add_heading(doc, text, level=1):"""添加标题"""heading = doc.add_heading(text, level=level)heading.alignment = WD_PARAGRAPH_ALIGNMENT.LEFTreturn headingdef add_paragraph(doc, text, bold=False, size=11):"""添加段落"""para = doc.add_paragraph()run = para.add_run(text)run.font.size = Pt(size)run.font.name = '微软雅黑'if bold:run.bold = Truereturn paradef add_table_with_data(doc, headers, data):"""添加表格"""table = doc.add_table(rows=1, cols=len(headers))table.style = 'Light Grid Accent 1'# 添加表头header_cells = table.rows[0].cellsfor i, header in enumerate(headers):header_cells[i].text = headerfor paragraph in header_cells[i].paragraphs:for run in paragraph.runs:run.font.bold = Truerun.font.size = Pt(10)run.font.name = '微软雅黑'# 添加数据行for row_data in data:row = table.add_row()for i, cell_data in enumerate(row_data):row.cells[i].text = str(cell_data)for paragraph in row.cells[i].paragraphs:for run in paragraph.runs:run.font.size = Pt(9)run.font.name = '微软雅黑'return tabledef format_schema_type(schema):"""格式化 schema 类型"""if not schema:return "any"schema_type = schema.get('type', 'object')if schema_type == 'array':items = schema.get('items', {})item_type = format_schema_type(items)return f"array<{item_type}>"elif schema_type == 'object':properties = schema.get('properties', {})if properties:props_str = ', '.join([f"{k}: {format_schema_type(v)}" for k, v in properties.items()])return f"{{{props_str}}}"return "object"return schema_typedef parse_swagger_to_word(swagger_file, output_file):"""解析 Swagger JSON 并生成 Word 文档"""# 读取 Swagger JSON 文件with open(swagger_file, 'r', encoding='utf-8') as f:swagger_data = json.load(f)# 创建 Word 文档doc = Document()# 设置文档标题title = doc.add_heading(swagger_data['info']['title'], level=0)title.alignment = WD_PARAGRAPH_ALIGNMENT.CENTER# 添加基本信息add_heading(doc, '文档信息', level=1)info = swagger_data.get('info', {})add_paragraph(doc, f"版本: {info.get('version', 'N/A')}")if info.get('description'):add_paragraph(doc, f"描述: {info.get('description')}")# 添加服务器信息servers = swagger_data.get('servers', [])if servers:add_heading(doc, '服务器地址', level=1)for server in servers:add_paragraph(doc, f"• {server.get('description', 'N/A')}: {server.get('url', 'N/A')}")# 添加认证信息security_schemes = swagger_data.get('components', {}).get('securitySchemes', {})if security_schemes:add_heading(doc, '认证方式', level=1)for name, scheme in security_schemes.items():add_paragraph(doc, f"• {name}: {scheme.get('type', 'N/A')} - {scheme.get('scheme', 'N/A')}")# 添加 API 接口文档add_heading(doc, 'API 接口列表', level=1)paths = swagger_data.get('paths', {})api_count = 0for path, methods in paths.items():for method, details in methods.items():api_count += 1# 接口标题summary = details.get('summary', '无描述')add_heading(doc, f"{api_count}. {summary}", level=2)# 基本信息表basic_info = [['接口路径', path],['请求方法', method.upper()],['标签', ', '.join(details.get('tags', []))],]add_table_with_data(doc, ['属性', '值'], basic_info)doc.add_paragraph()# 描述description = details.get('description')if description and description.strip():add_paragraph(doc, f"描述: {description.strip()}", size=10)doc.add_paragraph()# 请求参数parameters = details.get('parameters', [])if parameters:add_heading(doc, '请求参数', level=3)param_data = []for param in parameters:param_name = param.get('name', 'N/A')param_in = param.get('in', 'N/A')param_required = '是' if param.get('required', False) else '否'param_type = param.get('schema', {}).get('type', 'string')param_desc = param.get('description', param.get('schema', {}).get('description', ''))param_default = param.get('schema', {}).get('default', '')param_data.append([param_name,param_in,param_required,param_type,param_desc,str(param_default) if param_default else '-'])add_table_with_data(doc,['参数名', '位置', '必填', '类型', '说明', '默认值'],param_data)doc.add_paragraph()# 请求体request_body = details.get('requestBody')if request_body:add_heading(doc, '请求体', level=3)content = request_body.get('content', {})for content_type, content_details in content.items():add_paragraph(doc, f"Content-Type: {content_type}", size=10)schema = content_details.get('schema', {})properties = schema.get('properties', {})required_fields = schema.get('required', [])if properties:body_data = []for prop_name, prop_details in properties.items():prop_type = prop_details.get('type', 'string')prop_desc = prop_details.get('description', '')prop_required = '是' if prop_name in required_fields else '否'prop_default = prop_details.get('default', '')prop_example = prop_details.get('example', '')body_data.append([prop_name,prop_required,prop_type,prop_desc,str(prop_default) if prop_default else '-',str(prop_example) if prop_example else '-'])add_table_with_data(doc,['字段名', '必填', '类型', '说明', '默认值', '示例'],body_data)doc.add_paragraph()# 响应responses = details.get('responses', {})if responses:add_heading(doc, '响应', level=3)response_data = []for status_code, response_detail in responses.items():response_desc = response_detail.get('description', 'N/A')response_data.append([status_code, response_desc])add_table_with_data(doc,['状态码', '说明'],response_data)doc.add_paragraph()# 添加分隔线doc.add_paragraph('_' * 80)doc.add_paragraph()# 保存文档doc.save(output_file)print(f"✓ 接口文档已生成: {output_file}")print(f"✓ 共解析 {api_count} 个接口")if __name__ == '__main__':swagger_json_file = '/Users/baai/Desktop/workspace/hei-large-screen/static/swagger.json'output_word_file = '/Users/baai/Desktop/workspace/hei-large-screen/API接口文档.docx'parse_swagger_to_word(swagger_json_file, output_word_file)
安装依赖：
pip install python-docx