ScanAPI：自动化API测试与文档生成的神器

企业开发 2025-04-12 00:11:27 阅读次数: 0

ScanAPI简介

ScanAPI是一个基于Python的工具，通过编写简单的YAML或JSON文件来定义API的规格和测试用例。然后，ScanAPI会根据这些规格自动发起请求，并生成详细的HTML报告，其中包括请求的响应结果、测试结果以及API文档。这一特性极大地简化了API测试流程，同时确保了文档的准确性和实时性。

核心功能

API规格定义

ScanAPI的核心功能之一是以YAML或JSON格式定义API的规格。这包括API的名称、基础URL、请求路径、HTTP方法等信息。例如：

endpoints:
  - name: scanapi-demo
    path: http://demo.scanapi.dev/api/v1
    requests:
      - name: list_all_users
        path: users/
        method: get

上述YAML文件定义了一个名为“scanapi-demo”的API，其基础URL为http://demo.scanapi.dev/api/v1。在该API下，定义了一个名为“list_all_users”的请求，其路径为/users/，HTTP方法为GET。

自动化测试

ScanAPI的另一个强大功能是自动化测试。可以在API规格文件中定义测试用例，包括测试的名称、断言条件等。例如：

tests:
  - name: status_code_is_200
    assert: $response.status_code == 200

上述测试用例检查响应的状态码是否为200。ScanAPI会自动发起请求，并根据定义的测试用例进行断言。如果断言失败，测试将标记为失败，并在生成的HTML报告中详细记录失败的原因。

HTML报告生成

ScanAPI能够自动生成详细的HTML报告，其中包括请求的响应结果、测试结果、请求和响应的头部信息、请求体等。这些报告对于调试和分享测试结果非常有用。
在这里插入图片描述

使用方式

使用ScanAPI非常简单。首先，需要安装ScanAPI：

pip install scanapi

安装完成后，需要编写API规格文件，并保存为YAML或JSON格式。然后，在命令行中运行ScanAPI命令，并指定API规格文件的路径：

scanapi run <file_path>

ScanAPI将读取API规格文件，自动发起请求，并生成HTML报告。生成的HTML报告将保存在当前目录下的scanapi-report.html文件中。

实际应用案例

假设正在开发一个名为“MyAPI”的API，该API提供了用户信息的查询功能。可以使用ScanAPI来定义API的规格、编写测试用例并生成HTML报告。

首先，编写一个YAML文件来定义API的规格：

endpoints:
  - name: MyAPI
    path: http://api.example.com/v1
    requests:
      - name: get_user_info
        path: users/{
    
    user_id}
        method: get
        params:
          user_id: 123
        headers:
          Authorization: Bearer <token>
        tests:
          - name: status_code_is_200
            assert: $response.status_code == 200
          - name: user_id_is_correct
            assert: $response.json().user_id == 123

在上述YAML文件中，定义了一个名为“MyAPI”的API，其基础URL为http://api.example.com/v1。在该API下，定义了一个名为“get_user_info”的请求，其路径包含了一个动态参数user_id，HTTP方法为GET。还为该请求定义了两个测试用例：一个检查响应的状态码是否为200，另一个检查响应中的user_id字段是否与请求中的user_id参数一致。

然后，在命令行中运行ScanAPI命令：