使用 Web API 测试器

最后更新时间：2024 年 05 月

介绍

Web API 测试器 是内置在 SnapDevelop 中的 API 测试工具， 允许您在不离开应用程序的情况下快速测试 API。

它提供以下功能：

• 友好的图形界面，可以更好地帮助您构建请求和读取响应信息

• 正常测试模式和调试测试模式两种模式

• 支持多种认证模式（基本授权、不记名令牌和 OAuth 2.0）

• 可以在请求和响应中启用 cookie

• 支持自动生成模拟数据作为请求参数

• 能够在请求中将复杂对象作为主体参数发送

  Web API 测试器 支持将复杂数据模型作为 Web API 请求（执行 CRUD 操作）的参数，甚至提供一个接口来引入对象的数据属性。

您可以对工程中的API进行测试，或从 Swagger 导入 API， 或从头开始创建自己的 API。

配置 Web API 测试器

Web API 测试器 的常规设置可以通过菜单 测试 > 选项 找到。您可以通过以下设置来控制 Web API 测试器 的全局行为：

• 启用 Cookies -- 如果启用该选项， Web API 测试器将主动存储服务器 cookie，并将 cookie 用于后续请求。
• 启用参数模拟功能 -- 启用/禁用"参数"选项卡中的模拟功能。
• 打开 API 时自动模拟参数数据 -- 打开 API 时自动启动参数模拟功能。
• 允许自动重定向 -- 如果启用该选项，并且 Web API 测试器发送请求的网站已配置重定向，则 Web API 测试器会向重定向的 URL 发出测试请求。并可设置允许的最大重定向次数。
• 响应数据允许的最大值 -- 配置响应数据允许的最大值。如果请求返回的响应超过特定大小，Web API 测试器可以触发下载提示，要求您将响应下载到文本文件，或是抛出异常。
• 请求超时 -- 您可以配置发送 Web API 测试请求和请求超时之间的时间间隔。由于在调试模式下请求通常需要更长的时间才能完成，因此在调试模式下应将间隔设置为比在正常模式下长得多的时间段。
• 启用代理 -- 如果启用该选项，Web API 测试器将使用代理设置。
  • 使用系统默认代理设置 -- 如果启用该选项则 Web API 测试器将使用系统的默认代理设置。
  • 配置全局代理设置 -- 如果启用该选项则可以指定全局代理设置，包括代理服务器地址及端口号、是否使用代理认证（如使用则输入用户名和密码）、需要排除的主机或域名。

Web API 测试器用户界面

要打开 Web API 测试器，请右键单击代码编辑器视图，然后选择 运行测试；或者选择菜单 测试 > Web API 测试器。

工具栏有以下按钮：

• 在视图中运行所有测试 -- 运行当前视图中包含的所有测试。
• 运行 -- 运行当前选中的测试。点击旁边的箭头将显示更多运行选项。
• 重复上次运行 -- 重复上次运行的测试。
• 运行失败的测试 -- 运行在上一次运行中不成功的测试。
• 添加 -- 创建一个新的测试。或者点击旁边的箭头选择从 Swagger Web API 导入。
• 全部展开 -- 展开视图中的所有节点。
• 全部收缩 -- 折叠视图中的所有节点。
• 选项 -- 打开 Web API 测试器的常规设置窗口。

请求树形图

Web API 测试器的树形图按以下类别进行分组和显示请求：

• 项目列表
• 历史记录
• Swagger
• 自定义

所有请求条目都显示了一个图标，指示其上次运行的状态。绿色表示成功，红色表示失败，黄色表示警告；同时还显示请求方法（GET、POST 、PUT 等）。

项目

该分组下的测试通过解析项目中的控制器（Controller）文件生成。您可以对它们做修改，但关闭选项卡时这些修改会丢失。测试的名称为方法的签名（方法+参数）。如果这些方法需要参数，参数将被添加到请求模板中：

历史

该分组包含到目前为止已执行的请求的历史记录，并按其相对日期进一步分组。您对这些请求所作的更改将不会保留。

Swagger

当您导入 Swagger API（通过单击 添加 > 添加 Swagger Web API）时，会自动创建一个 Swagger 分组。您对该组中的请求所作的更改将不会保留。

如需导入 Swagger API，请参考 导入 Swagger API 小节。

自定义

该分组包含用户创建的请求。您对自定义请求所做的更改将会被保存下来。

如需添加一个自定义请求，请参考 自定义 Web API 小节。

测试详细信息摘要

此视图显示有关当前选定节点的信息：

请求详细信息视图

当您双击树形图中的请求时，可以在单独的视图中看到其详细信息：

工具栏操作

详细信息视图窗口的工具栏包含以下按钮：

图标	按钮	描述
	转到代码	跳到定义当前请求的代码段。
	还原	将请求的设置恢复为默认值，也就是将参数、模拟、请求头等恢复到此窗口刚打开时的状态。
	历史记录	该请求的发送记录。
	停止当前运行的项目	运行测试时，Web API 测试器会运行接口对应的应用程序。如果您对代码进行了任何更改，需要重新启动服务后，更改才会生效。注意，如果您同时测试多个程序的接口，需要检查这些程序使用的端口是否有冲突。
	选项	打开 SnapDevelop 的 Web API 测试器常规设置。
	默认请求头设置	打开默认请求头设置窗口（见下文）。
	默认认证信息设置	打开默认认证信息设置窗口（见下文）。
	模拟设置	允许为请求定义默认的模拟设置。模拟是指"模拟数据"，即随机生成的数据。在此窗口中，您可以定义如何生成模拟数据（字符长度、数字最小值和最大值等）。
	环境	新建在不同场景中用于请求参数或 URL 的环境变量，或者编辑现有的环境变量。

默认请求头设置

默认请求头设置 窗口允许您设置：

1. 所有 API 默认请求头 -- 这些请求头将应用到所有解决方案的 API。

2. 当前解决方案 API 默认请求头 -- 这些请求头仅应用于当前解决方案的 API。

点击 添加 按钮可以添加新的请求头，点击 删除 图标（）可以删除请求头。

默认认证设置

配置所有请求默认使用的认证方案。

有关如何使用此功能的详细信息，请参阅 认证。

参数

参数 选项卡为请求的查询、表单、主体和标头配置参数。

点击 添加 按钮插入新参数（或点击旁边的箭头选择插入特定类型的参数）。

添加新参数时，可以配置以下内容：

1. 名称 -- 参数的名称。

2. 数据类型 -- 参数的数据类型。仅用于 IDE，因为 HTTP 请求中的参数始终是字符串（或者是文件，base64 编码）。

3. 值 -- 参数的实际值。

4. 删除 -- 删除参数。

5. 模拟 -- 模拟设置（即如何生成此参数的模拟数据）。只有当 模拟 列中启用了 模拟 功能时，才会启用此设置。

6. 类型 -- 参数的类型（查询、表单、主体、请求头）。查询 参数嵌入在请求的 URL 中， 主体 参数成为请求的主体。

对于对象类型，其公共属性将显示为单独的参数。

请求头

请求头 选项卡配置请求的标头。如果在 默认请求头设置 中配置了默认请求头，则会自动读取此配置。

主体

主体 选项卡允许您查看和修改请求主体的内容以及选择主体提交时的格式。

您可以通过以下三种方式修改主体内容：

1. 自动生成 -- 显示请求的主体，就跟使用 参数 选项卡中定义的 主体 类型参数一样。

2. 原始数据 -- 允许手动输入请求主体的内容。

   支持以下操作：

   导入 -- 从文本文件中导入文本。

   检索 -- 从 HTTP 请求检索文本，该请求可以源自项目本身，也可以是外部的。

   拷贝 -- 将内容从编辑器复制到剪贴板。

   清空 -- 清除编辑器。

3. 二进制。允许在请求主体中发送二进制文件。

修改主体内容后，您可以通过格式选择器决定主体提交时的格式；它会更改 Content-Type 标头。

认证

认证 选项卡配置用于请求的身份验证方案。您可以从以下认证方案中进行选择：

• 无认证：不使用身份验证。

• 基本认证：一种简单的方案，通过身份验证标头发送以 Base 64 编码的用户名和密码。

• Bearer Token：一种安全令牌（通常由 API 或身份验证机构颁发），用于标识此请求已通过身份验证。

• API Key：一对包含了只有客户端和服务器知晓的令牌的键值，可以通过标头或作为查询参数发送。

• OAuth 2.0：使用 OAuth 2.0 协议进行请求授权。请参阅下一小节。

OAuth 2.0

OAuth 2.0 是一种授权协议，它允许 API 客户端对 Web 服务器上的用户数据进行有限访问。 像GitHub、Google 和 Facebook等API都使用了OAuth 2.0。 OAuth 使用流身份验证方案，它允许资源所有者（用户）共享来自资源服务器的受保护内容，而无需共享其凭据。

有关 OAuth 2.0 协议的更多信息，请点击 此链接。

创建访问令牌

要创建访问令牌，请单击获取新的访问令牌：

这将打开 获取新的访问令牌 窗口，您可以在其中选择要使用的授予类型并填写相关信息。有关授权类型的更多信息，请参阅 OAuth 2.0 规范。

填写完数据后，点击请求。

授权请求将被发送及保存（如成功）。

创建后，可以在认证令牌选择器中选择使用它：

管理访问令牌

对于已创建的访问令牌，可以单击 令牌管理 按钮进行管理。

这将打开 令牌管理 窗口，该窗口将显示所有已创建并保存的令牌。

您可以逐个删除令牌，或一次删除所有令牌，或仅删除过期的令牌。

Cookies

Cookies 选项卡配置请求将使用的 Cookie。它包含以下工具栏按钮：

• 新增 Cookie -- 显示配置新 Cookie 的窗口。
• 导入 -- 导入包含 Cookie 设置的文本文件并将其导入请求。
• 导出 -- 将当前 Cookie 设置导出到文本文件。

点击 新增 Cookie 后将打开 Cookie 的编辑窗口，可以配置 Cookie 的属性。

前置操作

前置操作 选项卡允许您设置在发送请求前执行哪些操作。

后置操作

后置操作 选项卡允许您设置在发送请求后执行哪些操作。

使用 Web API 测试器

导入 Swagger API

Web API 测试器 可以将 Swagger API 导入到树形图，并允许您使用以下功能：数据模拟、对象参数、OAuth 2.0 身份验证等。

要导入 Swagger Web API，请单击 添加 > 添加 Swagger Web API 按钮。

输入 swagger.json 文件的 URL。

该 json 文件中的所有 API 将被添加到 Web API 测试器树形图中。

自定义 Web API

如需添加一个自定义请求，点击 添加 图标，然后选择请求类型，输入请求 URL，设置参数、请求头、主体等等，最后点击 保存 下拉图标，选择 另存为。

给请求分组命名或选择一个已有分组，点击 保存。

该 API 将被添加到 Web API 测试器树形图中。

运行测试

启动 Web API 服务

运行测试（或者发送请求）时，如果 SnapDevelop 检测到对应的 Web API 服务没有启动，会弹出 启动项目 窗口。其中 配置项 的值为工程属性面板的 调试 页面中的 配置文件 名字。您可以在此窗口中选择需要启动的项目以及配置项，然后点击 确定。

从 Web API 测试器树形图中运行

右键单击 Web API 测试器树形图中的请求，然后选择 运行：

执行结果将显示在底部的测试详细信息摘要面板中：

如果测试失败（例如，API 返回失败结果代码），错误将显示在同一面板中，并且显示相关附加信息：

这种运行测试的方法对于快速评估测试并查看它是否成功更有用。对于需要指定请求的参数、标头和认证方案，以及查看响应主体，请参见以下方法。

从 Web API 测试器详细信息视图中运行

通过双击一个测试打开 Web API 测试器详细信息视图。

根据需要设置请求，然后单击 发送 按钮。

响应内容将显示在底部的视图：

数据模拟

数据模拟是一种使用随机生成的数据来"模拟"用户输入的技术。例如，模拟用户对请求参数的输入。 Web API 测试器提供了模拟各种类型的数据以模拟 API 参数的功能。

要使用模拟，请选择 参数 选项卡，然后选择 模拟 复选框以启用数据模拟：

启用后，将根据其数据类型为每个参数设置默认的模拟设置。要选择不同的模拟类型或调整其设置，请单击参数的模拟列中的箭头：

您可以从左侧列表中选择不同的模拟类型，然后在右侧调整其设置。每个模拟器将根据它们生成的类型具有不同的设置。

例如，String 模拟器具有以下设置：

• 字符串 -- 从中生成字符串的字符集。
• Min -- 字符串的最小长度。
• Max -- 字符串的最大长度。

你也可以通过点击此选项卡窗口工具栏上的 模拟设置 图标（），设置全局的数据模拟规则。

规则会依次按照类型和参数名进行匹配。

例如，在 string 类型后设置对应的模拟规则 A，则会对所有的 string 类型生效；如果点击 string 后面的 + 号，会在 string 类型下新增一个子规则，假如在 属性名称 中填入 name 并设置相应的规则 B，那么对于 string 类型的 name 属性，都会应用规则 B，其他 string 属性仍应用规则 A。

从代码编辑器中运行

右键单击映射到请求的控制器方法，然后选择 运行测试：

Web API 测试器将打开。双击树形图中的请求，其相应的详细视图将打开，点击 发送。请求将运行。

调试测试

调试测试意味着在调试模式下运行 Web API。当处理请求的代码遇到断点时，执行将暂停，您可以逐行检查代码执行和变量。有关调试的更多信息，请点击此链接。

从 Web API 测试器面板中调试

首先请在代码中添加断点，然后通过以下方式调试代码：

a) 左侧树形图中选择一个测试，然后从工具栏按钮中选择 调试：

b) 右键单击树形图中的测试，然后选择 调试：

从 Web API 测试器详细信息视图中调试

在请求的详细视图中，点击 发送 按钮的箭头，然后选择 调试：

单击 调试 按钮后，Web API 将在调试模式下重新启动并且测试将运行。如果代码路径中有断点，执行会暂停，您会被引导到断点，否则，请求会正常执行。

从代码编辑器中调试

右键单击映射到请求的控制器方法，然后选择 调试测试：

相应的详细视图将打开，请求将在调试模式下自动运行。