如何将OpenAPI 3.0 YAML/JSON文件转换为Word文档？

以下是几种实用的实现方案，可解决你之前PDF转换效果不佳的问题：

1. 使用OpenAPI Generator直接生成Word文档 #

OpenAPI Generator支持直接输出docx格式的文档，且支持自定义模板调整排版样式：

• 先安装OpenAPI Generator（可通过npm或直接下载jar包）
• 执行生成命令：

  openapi-generator generate -i your-openapi-spec.yaml -g docx -o ./openapi-word-output
  

  参数说明：
  • -i：指定你的OpenAPI YAML/JSON输入文件
  • -g docx：指定生成器为docx格式
  • -o：指定输出目录
• 若默认样式不符合需求，可自定义Freemarker模板（OpenAPI Generator的docx生成器基于Freemarker），调整标题层级、字体、段落格式等细节。

2. 用Python脚本自定义生成Word文档 #

通过Python读取OpenAPI spec，再利用python-docx库手动构建Word文档，完全掌控排版逻辑：

import yaml
from docx import Document
from docx.shared import Pt
from docx.enum.text import WD_ALIGN_PARAGRAPH

# 读取OpenAPI YAML文件
with open('your-openapi-spec.yaml', 'r', encoding='utf-8') as f:
    spec_data = yaml.safe_load(f)

# 初始化Word文档
doc = Document()

# 添加文档标题
title_heading = doc.add_heading(spec_data['info']['title'], level=1)
title_heading.alignment = WD_ALIGN_PARAGRAPH.CENTER
title_heading.style.font.size = Pt(18)

# 添加文档基本信息
doc.add_paragraph(f"版本：{spec_data['info']['version']}", style='Body Text')
doc.add_paragraph(f"描述：{spec_data['info']['description']}", style='Body Text')
doc.add_page_break()

# 遍历所有接口路径
doc.add_heading('接口详情', level=2)
for path, methods in spec_data['paths'].items():
    path_heading = doc.add_heading(f"路径：{path}", level=3)
    path_heading.style.font.color.rgb = doc.styles['Heading 3'].font.color.rgb
    
    for method, details in methods.items():
        doc.add_heading(f"请求方法：{method.upper()}", level=4)
        doc.add_paragraph(f"接口摘要：{details.get('summary', '无')}")
        
        # 添加请求参数（示例）
        if 'parameters' in details:
            doc.add_heading('请求参数', level=5)
            for param in details['parameters']:
                doc.add_paragraph(f"- {param['name']}（{param['in']}）：{param.get('description', '无描述')}，类型：{param['schema']['type']}")
        
        # 添加响应信息（示例）
        if 'responses' in details:
            doc.add_heading('响应示例', level=5)
            for status, resp_details in details['responses'].items():
                doc.add_paragraph(f"状态码：{status} - {resp_details.get('description', '无描述')}")

# 保存文档
doc.save('openapi-custom.docx')

这种方式可以根据你的需求灵活调整内容展示顺序、样式，完全避免自动转换的排版问题。

3. Markdown中转法（适合偏好Markdown排版的场景） #

先将OpenAPI spec转成Markdown，再通过Pandoc转换为Word文档：

• 用redoc-cli生成Markdown文档：

  redoc-cli bundle your-openapi-spec.yaml -o openapi-doc.md
  

• 用Pandoc将Markdown转成Word，还可指定自定义模板优化样式：

  pandoc openapi-doc.md --reference-doc=your-custom-template.docx -o openapi-final.docx
  

  其中your-custom-template.docx是你预先设置好样式（如标题字体、段落间距）的Word模板，能让最终文档的排版更符合需求。

内容的提问来源于stack exchange，提问作者wocsom