在我们的开发工作中，API 文档不仅是一个重要的参考资料，也是团队沟通的桥梁。尽管有许多工具可以帮助我们创建和管理 API 文档，但有时我们可能需要根据特定格式或模板来生成文档。本文介绍如何使用 Python 脚本自动将 Swagger（现在称为 OpenAPI）规范的 JSON 文件转换为可读性更强的 Markdown 文档。

Swagger / OpenAPI 简介

Swagger 是一个 API 描述格式，用于描述 RESTful API 的结构和行为。Swagger 规范现在由 OpenAPI Initiative 维护，并被称为 OpenAPI 规范。Swagger JSON 文件包含了所有关于 API 的细节，包括路径、方法、参数和响应。

为什么需要 Markdown 格式的文档？

Markdown 是一种轻量级标记语言，它允许我们用易于阅读和编写的纯文本格式来撰写文档。Markdown 文件可以轻松转换为 HTML 或其他格式，并且可以很容易地通过版本控制系统进行管理。这使得 Markdown 成为撰写和分享 API 文档的理想选择。

脚本概览

我们将创建一个 Python 脚本，它会读取 Swagger JSON 文件，提取相关信息，并将其格式化为 Markdown 格式。脚本的核心是 generate_markdown 函数，该函数遍历 JSON 文件中的路径和方法，提取摘要、描述、URI、参数和响应数据，然后组装成 Markdown 文本。

准备工作

在开始之前，请确保您已安装 Python。接下来，准备一个 Swagger JSON 文件，我们将使用这个文件作为输入数据来生成 Markdown 文档。

脚本实现

首先，我们定义一个函数来处理参数的生成：

def generate_parameters(parameters, param_in):
    # 这里是处理和生成参数部分的代码
    result = []
    filtered_params = [p for p in parameters if p['in'] == param_in]
    if filtered_params:
        result.append("| 参数 | 是否必填 | 参数类型 | 说明 | 示例 |\n")
        result.append("| --- | --- | --- | --- | --- |\n")
        for param in filtered_params:
            name = param['name']
            required = "是" if param.get('required', False) else "否"
            param_type = param['schema']['type'] if 'schema' in param else "未知"
            description = param.get('description', '无')
            example = param.get('example', '无')
            result.append(f"| {name} | {required} | {param_type} | {description} | {example} |\n")
    else:
        result.append("无\n\n")
    return ''.join(result)

然后，我们创建 generate_request_body 和 generate_responses_table 函数来处理请求体和响应：

def generate_request_body(request_body, swagger_data):
    # 这里是处理请求体的代码
    content = request_body.get('content', {})
    schema = next(iter(content.values())).get('schema', {})
    ref = schema.get('$ref', '')
    return generate_schema_table(ref, swagger_data, 'body')

def generate_responses_table(responses, swagger_data):
    # 这里是创建响应表格的代码
    result = []
    for status, response in responses.items():
        description = response.get('description', '')
        content = response.get('content', {})
        schema = next(iter(content.values())).get('schema', {})
        ref = schema.get('$ref', '')
        result.append(f"#### HTTP 状态码: {status}\n\n")
        result.append(f"{description}\n\n")
        result.extend(generate_schema_table(ref, swagger_data, 'response'))
    return result

最后，我们实现 generate_markdown 函数，它将使用上述辅助函数来构建完整的 Markdown 文档：

def generate_markdown(swagger_data):
    markdown_output = []

    # 这里是遍历 Swagger JSON 并生成 Markdown 的代码
    paths = swagger_data.get('paths', {})
    for endpoint, methods in paths.items():
        for http_method, details in methods.items():
            title = details.get('summary', 'API Summary')
            markdown_output.append(f"## {title}\n")
            markdown_output.append(f"### 接口功能介绍\n\n{details.get('description', 'No description provided.')}\n")
            markdown_output.append(f"### URI\n\n`{http_method.upper()} {endpoint}`\n\n")
            
            # Parameters
            markdown_output.append("**路径参数**\n\n")
            markdown_output.append(generate_parameters(details.get('parameters', []), 'path'))
            
            markdown_output.append("**Query参数**\n\n")
            markdown_output.append(generate_parameters(details.get('parameters', []), 'query'))
            
            markdown_output.append("**请求头header参数**\n\n")
            markdown_output.append(generate_parameters(details.get('parameters', []), 'header'))
            
            # Request body
            markdown_output.append("### 请求参数\n\n")
            markdown_output.append("**请求体body参数**\n\n")
            if 'requestBody' in details:
                request_body_data = generate_request_body(details['requestBody'], swagger_data)
                markdown_output.append(''.join(request_body_data))
            else:
                markdown_output.append("无\n\n")
            
            # Responses
            markdown_output.append("### 响应参数\n\n")
            responses = details.get('responses', {})
            response_data = generate_responses_table(responses, swagger_data)
            markdown_output.append(''.join(response_data))
            
            markdown_output.append("\n---\n")
    
    return ''.join(markdown_output)

使用脚本

一旦脚本完成，运行脚本很简单：

python path_to_script.py

确保将 path_to_script.py 替换为脚本文件的实际路径。脚本会生成 Markdown 文档并将其保存到您指定的文件中。

结语

通过这种方式，我们可以将 Swagger JSON 转换为更易于人们阅读和编辑的 Markdown 格式，从而提高 API 文档的可访问性和可维护性。这个自动化的过程节省了手动编写文档的时间，并且可以轻松集成到持续集成/持续部署 (CI/CD) 流程中，确保文档始终保持最新。