在我們的開發工作中，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) 流程中，確保文檔始終保持最新。