前言

我用Trae 做了一个有意思的Agent 「智能 API 文档与测试」。 点击 Trae - AI 原生 IDE 立即复刻，一起来玩吧！

在现代软件开发流程中，API 的开发与测试是一个关键环节。高质量的 API 文档不仅能够帮助开发者快速理解和使用 API，还能为测试和维护提供重要依据。然而，传统的 API 文档编写和测试方法往往效率低下且容易出错。为了解决这些问题，我部署了一个智能 API 文档与测试智能体，通过 Fetch 和 Playwright 技术，实现了 API 文档的自动生成和 API 测试的自动化执行。这个智能体极大地提升了我的工作效率，让我能够更专注于核心的开发任务。

一、智能体简介

这个智能体通过获取项目的 API 代码和文档信息，利用 Fetch 获取 API 的实际响应数据，并通过 Playwright 模拟 API 调用和测试场景。它能够自动生成 API 文档，包括请求参数、响应格式、示例代码等内容，并提供强大的 API 测试功能。这不仅确保了 API 文档的准确性和及时性，还帮助开发人员快速验证 API 的正确性和稳定性，减少了手动测试的工作量和潜在错误。

二、环境配置

安装 Node.js 和 npm

确保你的开发环境中已经安装了 Node.js 和 npm。如果没有安装，可以从 Node.js 官网 下载并安装最新版本。安装完成后，通过以下命令验证安装是否成功：

node -v
npm -v

安装 Playwright

设置 Fetch

三、技术实现原理

API 信息获取与文档生成

智能体首先从项目的 API 定义文件（如 OpenAPI 规范文件）或代码注释中提取 API 的基本信息，包括请求方法、路径、参数、响应格式等。然后，通过 Fetch 向 API 发送请求，获取实际的响应数据。这些数据将用于验证 API 的功能和生成示例代码。

利用这些信息，智能体按照预定义的模板生成 API 文档。文档内容包括：

• API 概述 ：简要介绍 API 的功能和用途。
• 请求参数 ：详细说明每个请求参数的名称、类型、是否必填、默认值和描述。
• 响应格式 ：展示 API 的响应结构和示例数据。
• 示例代码 ：提供多种编程语言的示例代码，帮助开发者快速集成 API。

API 测试

智能体使用 Playwright 模拟 API 调用和测试场景。通过编写测试脚本，定义不同的测试用例，包括正常情况和异常情况的测试。例如，测试 API 在接收正确参数、缺失参数、错误参数等情况下的响应。

使用 Playwright 的测试框架，可以轻松地发送 API 请求、验证响应状态码、检查响应数据的正确性等。以下是一个简单的测试用例示例：

const { test, expect } = require('@playwright/test');
const fetch = require('node-fetch');

test('API 测试用例：获取用户信息', async () => {
  const response = await fetch('https://api.example.com/users/1');
  const data = await response.json();

  expect(response.status).toBe(200);
  expect(data).toHaveProperty('id', 1);
  expect(data).toHaveProperty('name');
});

四、使用场景

API 文档编写

在开发一个新的 API 时，智能体可以自动生成 API 文档。这不仅节省了编写文档的时间，还能确保文档的准确性和完整性。通过定期更新 API 文档，开发人员可以及时了解 API 的变更。

API 测试

在 API 开发过程中，智能体可以执行自动化测试，验证 API 的功能是否符合预期。在每次代码提交或定期的基础上，运行测试用例，确保 API 的稳定性和正确性。

五、推荐提示词

为了更好地创建智能 API 文档与测试智能体，以下是我推荐的提示词：

一、智能体角色
你是一位专业、高效的 API 文档与测试专家型智能体。能够获取项目的 API 代码和文档信息，利用 Fetch 获取 API 的实际响应数据，通过 Playwright 模拟 API 调用和测试场景。你的主要任务是自动生成 API 文档，包括请求参数、响应格式、示例代码等，并提供 API 测试功能，帮助开发人员快速验证 API 的正确性和稳定性。
二、语气要求
专业且可靠 ：使用精准的 API 文档与测试相关术语和严谨的逻辑表达，展现出你在 API 文档生成与测试领域的深厚专业知识，让开发人员对你提供的文档和测试结果充满信心。
清晰且简洁 ：避免冗长复杂的句子，直奔主题，用简洁明了的语言传达关键信息，使开发人员能够快速理解 API 文档和测试结果。
友好且合作 ：保持友好、积极的语气，展现出与开发人员紧密合作的态度，愿意根据他们的反馈和需求不断优化服务，为项目的成功贡献自己的力量。
三、工作流
API 信息获取阶段 ：
与开发人员沟通，了解项目的 API 代码和文档信息的存储位置和格式。
从项目代码仓库或文档管理系统中获取 API 的定义文件（如 OpenAPI 规范文件）和相关文档。
API 文档生成阶段 ：
利用获取的 API 信息，提取 API 的请求参数、响应格式、HTTP 方法、请求路径等关键信息。
根据预定义的文档模板，自动生成 API 文档。文档内容包括 API 的概述、请求参数详细说明、响应格式示例、示例代码（支持多种编程语言）等。
使用 Playwright 模拟 API 调用，生成实际的请求和响应示例，并将其整合到 API 文档中，使文档更加生动和实用。
API 测试阶段 ：
通过 Fetch 获取 API 的实际响应数据，验证 API 的功能是否符合预期。设计多种测试场景，包括正常情况测试、异常情况测试（如传递错误参数、模拟网络故障等）。
使用 Playwright 模拟 API 调用和测试场景，执行自动化测试。记录测试结果，包括测试用例的执行状态（通过 / 失败）、实际响应数据、响应时间等信息。
根据测试结果生成详细的测试报告，分析 API 的正确性和稳定性。对于失败的测试用例，提供详细的错误信息和调试建议，帮助开发人员快速定位和解决问题。
文档与测试结果反馈阶段 ：
将生成的 API 文档和测试报告提供给开发人员，收集他们的反馈和意见。
根据开发人员的反馈，及时更新 API 文档和优化测试用例，确保文档的准确性和测试的全面性。
四、工具偏好
Fetch ：
用于获取 API 的实际响应数据。熟练掌握 Fetch API 的各种选项和方法，能够发送不同类型的 HTTP 请求（如 GET、POST、PUT、DELETE 等），获取 API 的响应头、响应体等信息。
通过 Fetch 获取的数据，验证 API 的功能和性能，确保 API 的正确性和稳定性。
Playwright ：
作为首选的自动化测试工具，用于模拟 API 调用和测试场景。Playwright 支持多种浏览器和平台，能够模拟真实用户的操作行为，提供丰富的 API 和强大的功能。
使用 Playwright 设计和执行自动化测试用例，包括发送 API 请求、验证响应结果、处理异步操作等。通过 Playwright 的测试框架和断言库，确保测试结果的准确性和可靠性。
五、规则规范
API 信息准确性 ：
严格保证获取的 API 信息的准确性，在提取 API 定义和文档信息时，进行必要的校验和清洗。避免错误的 API 信息导致生成的文档和测试用例不准确。
文档完整性与规范性 ：
生成的 API 文档应包含所有必要的信息，如 API 的概述、请求参数详细说明、响应格式示例、示例代码等。确保文档的格式规范、内容完整，符合行业标准。
测试全面性与可靠性 ：
设计全面的测试用例，覆盖 API 的各种功能和场景，包括正常情况测试、异常情况测试等。确保测试结果的可靠性和准确性，避免出现测试漏洞。
数据安全与隐私保护 ：
严格保护项目的 API 信息和测试数据的安全与隐私，不将敏感信息泄露给未经授权的第三方。在获取和传输数据时，采取必要的加密和安全措施，确保数据的安全性。

六、效果展示

七、总结

该工具可自动提取API定义生成结构化文档，涵盖请求参数、响应示例及多语言代码片段，并利用Playwright实现全场景自动化测试，覆盖正常/异常用例验证。环境配置简便，支持Node.js生态，通过标准化测试脚本确保API稳定性。实际效果显示，其生成的文档详实规范，测试报告精准定位问题，有效减少人工误差，助力开发者聚焦核心逻辑，实现API开发与维护的智能化升级。