4. API文档解析

好，咱们进入第四章节。说实话，API文档解析这块，是我个人觉得整个自动化扫描流程里最容易被低估的一环。很多人觉得不就是读个JSON/YAML嘛，有什么难的？嗯，等你真正踩过坑就知道了。

4.1 为什么非要解析API文档？

你想想看，一个API安全扫描工具，如果连被测对象有哪些接口、参数长什么样都不知道，那它扫描个啥？说白了，API文档就是我们的「作战地图」。

我在项目中遇到过好几次这样的情况：开发团队给了个Swagger文档，结果里面路径写错了、参数类型标反了。如果直接拿这个文档去生成测试用例，那跑出来的结果全是废的。所以，解析文档不只是「读出来」，更是「校验和清洗」的过程。

4.2 OpenAPI/Swagger规范解析

OpenAPI规范（以前叫Swagger规范）是目前最主流的API描述标准。我习惯把它分成三个层次来理解：

• 信息层：API的标题、版本、描述等元数据
• 路径层：每个端点的HTTP方法、路径参数、请求体、响应体
• 组件层：复用的schema定义、安全方案、请求示例等

解析的时候，我一般用Python的openapi-parser或者prance库。举个例子：

import json
from prance import ResolvingParser

# 加载并解析OpenAPI文档
parser = ResolvingParser('api-spec.yaml')
spec = parser.specification

# 提取所有路径
for path, methods in spec['paths'].items():
    for method, details in methods.items():
        print(f"端点: {method.upper()} {path}")
        print(f"  描述: {details.get('summary', '无描述')}")
        # 提取参数
        parameters = details.get('parameters', [])
        for param in parameters:
            print(f"  参数: {param['name']} ({param['in']}) - {param.get('schema', {}).get('type', 'unknown')}")

4.3 从Swagger生成测试用例

解析完文档，下一步就是生成测试用例。这一步的核心思路是：把API文档中的每个端点、每种参数组合，映射成一条或多条测试用例。

我曾经犯过一个错误：只生成正常参数组合的用例，忽略了边界值和异常值。结果扫描报告出来，一堆高危漏洞都没扫到。后来我学乖了，生成用例时至少覆盖这三类：

用例类型	说明	示例
正常用例	参数完全符合规范	字符串长度在范围内、数字在范围内
边界用例	参数取边界值	空字符串、最大长度、最小值、最大值
异常用例	参数不符合规范	字符串传数字、必填字段缺失、SQL注入payload

生成代码大致长这样：

def generate_test_cases(spec):
    test_cases = []
    for path, methods in spec['paths'].items():
        for method, details in methods.items():
            # 基础用例：正常参数
            base_case = {
                'method': method.upper(),
                'path': path,
                'params': extract_default_params(details),
                'expected_status': 200
            }
            test_cases.append(base_case)
            
            # 边界用例：参数为空
            if details.get('parameters'):
                empty_case = deepcopy(base_case)
                empty_case['params'] = {p['name']: '' for p in details['parameters'] if p.get('required')}
                empty_case['expected_status'] = 400
                test_cases.append(empty_case)
                
            # 异常用例：注入payload
            inject_case = deepcopy(base_case)
            inject_case['params'] = inject_payloads(base_case['params'])
            inject_case['expected_status'] = [400, 403, 500]
            test_cases.append(inject_case)
    return test_cases

4.4 API端点提取与参数化

端点提取，说白了就是把API文档里的路径和参数「拆开」并「变量化」。为什么要这么做？因为同一个端点，不同环境（开发、测试、生产）的域名不一样，参数值也不一样。

我习惯的做法是：

1. 提取路径模板：把/api/v1/users/{userId}中的{userId}替换成占位符
2. 参数分类：路径参数、查询参数、请求头参数、请求体参数分开管理
3. 参数值数据源化：从CSV、数据库或配置文件读取实际值

举个例子：

# 端点模板化
endpoint_template = "/api/v1/users/{user_id}/orders/{order_id}"

# 参数化配置
params_config = {
    "user_id": {"type": "int", "source": "csv", "file": "user_ids.csv"},
    "order_id": {"type": "int", "source": "api", "endpoint": "/api/v1/orders/active"}
}

# 运行时动态替换
def resolve_endpoint(template, params_config):
    import requests
    # 从CSV读取user_id
    user_ids = read_csv(params_config['user_id']['file'])
    # 从API获取order_id
    order_ids = requests.get(params_config['order_id']['endpoint']).json()
    
    for uid in user_ids:
        for oid in order_ids:
            yield template.format(user_id=uid, order_id=oid)

4.5 实战中的常见坑

嗯，最后聊几个我踩过的坑，希望能帮你省点时间：

• 文档版本不一致：开发用的OpenAPI 3.0，你解析器只支持2.0，解析出来全是错的。建议统一用openapi-parser的最新版。
• 循环引用：有些文档里$ref互相引用，解析器直接死循环。记得设置max_depth限制。
• 枚举值遗漏：参数有枚举约束时，一定要把枚举值全部提取出来作为测试数据。我见过一个接口，枚举值有20多个，但文档里只写了3个，结果漏测了。
• 安全方案忽略：很多人在解析时只关注路径和参数，忽略了security字段。实际上，这个字段决定了你的扫描请求要不要带token、API key等认证信息。