Apifox Blog

「MCP Client」调试体验优化

使用 MCP 客户端调试 MCP 服务器时，响应内容的查看体验全面升级，提供更便捷的内容预览与验证功能。

1. 支持直接查看响应 Content 字段

使用 Apifox 调试 MCP 服务器时，可在「内容」标签页直接查看响应中的 Content 字段，无需从完整的 JSON 数据中手动查找。同时，「原始」标签仍保留完整 JSON 数据的查看功能，满足不同场景下的调试需求。

2. 支持 Markdown 渲染预览

当 MCP 响应中包含 Markdown 内容时，用户可在原始 Markdown 格式与渲染视图之间自由切换，直观查看格式化后的 Markdown 文档效果，提升内容查阅的便利性。

3. 支持预览图片

响应中的图片可直接在「预览」标签页显示，帮助开发者快速验证图片内容及其格式，提高调试效率。

「测试套件」持续升级

支持「并行」运行模式

测试套件新增「并行」运行能力，允许多个测试用例和场景同时执行。用户可以灵活配置并行执行规则，显著缩短整体测试时间，特别适合大规模测试场景，帮助团队更快速、更高效地完成测试任务。

运行模式说明：

串行：场景按序运行，支持变量在多场景步骤间持续传递
并行：多个场景并发运行，大幅提升速度。但需注意：并发会导致场景间的上下文隔离，依赖上游变量的场景可能运行失败

注：实际并行运行提速效果，跟运行机器的当时的可使用硬件资源强相关。

定时任务支持选择环境

创建测试套件定时任务时，支持选择运行环境，实现对测试套件在不同环境下自动化执行的精准控制，提升测试管理的灵活性。

新增「公用测试数据」，支持多场景共享使用

更新至最新版 Apifox 后，支持创建公用测试数据，可供多个测试场景共享使用，减少重复创建测试数据的工作，确保测试数据的一致性，更高效地管理测试资源，提升测试流程的标准化和可维护性。

测试报告详情页支持筛选失败用例

Apifox 在本次更新中对测试报告详情页进行了优化，新增了失败用例筛选功能，并支持查看步骤详情，帮助用户快速定位失败用例，深入了解每个失败步骤的执行情况。

同时，测试报告详情页针对不同查看场景优化了展示方式：

查看全部步骤时，以树状结构呈现，清晰展示步骤层级与执行上下文
筛选失败用例时，自动切换为扁平列表，汇总所有失败步骤，帮助快速定位问题

了解更多

当然，Apifox 产品团队为大家带来的新功能远不止以上这些：

优化了保护分支的交互
优化了接口使用预设的常用字段的交互
前后置脚本，支持 crypto 这个全局对象
解决 RAML 文件无法导入到 Apifox 的问题
解决在组织配置自定义角色时，部分情况下报 500 错误的问题
解决已删除的分支，没有解除接口 seo-自定义路径占用的问题
解决在线文档导航配置 url 校验的问题
解决自动化测试-循环次数为{{变量}}时，运行后报告显示循环 0 次的问题
解决在测试用例页面批量运行测试数据时，无法配置是否校验响应的问题
解决部分情况下，无法正确导入 Hoppscotch 的 Collection 的问题

除了新增功能，我们也对产品细节和使用体验进行了优化，具体修改内容可点击「阅读原文」前往 Apifox 更新日志查看，有任何问题欢迎在 Apifox 用户群与我们交流沟通。

私有化部署 - 为企业提供全方位服务方案 | Apifox

同时，Apifox 提供企业私有化部署版本，通过本地化部署、客制化服务，协助企业进一步提升研发团队效能。

Apifox 作为企业级 API 研发一体化协作平台，为企业提供从 API 管理、研发到自动化测试新的协同模式，量身定制专属解决方案，降低研发成本，提高协作效率，助力企业轻松完成 API 数字资产管理。

apifox

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能和更极致的使用体验！

Apifox 1 月更新｜MCP 调试、测试套件、测试报告重构、网络信息查看、Hoppscotch 导入

Apifox — Thu, 29 Jan 2026 06:26:10 GMT

Apifox 新版本上线啦！

看看本次版本更新主要涵盖的重点内容，有没有你所关注的功能特性：

支持创建 MCP Client 以调试 MCP Server
支持创建「测试套件」
测试报告全面重构，支持结构化展示
调试能力持续升级
支持查看 HTTP 版本、TLS 协议等网络信息
array 类型参数的子元素支持直接选择枚举值
调试 SSE 接口时，支持 \r\n 换行符
支持导入 Hoppscotch 的 Collection
优化邀请他人加入项目的流程
用户反馈优化
解决 MongoDB 数据库的密码包含特殊字符 % 时无法连接成功的问题
解决绑定了手机号的用户无法通过“忘记密码”功能重置密码的问题

将 Apifox 更新至最新版，一起开启全新体验吧！

私有化部署 - 为企业提供全方位服务方案 | Apifox

支持创建 MCP Client 以调试 MCP Server

Apifox 升级后，支持创建 MCP Client，开发者可以像调试 API 一样，直接调试 MCP Server 的Tools、Resources和 Prompts。同时支持STDIO和 Streamable HTTP 协议，并可自动配置 OAuth 2.0 认证流程，极大简化连接与认证流程，全面提升 AI Agent 的开发与调试效率。

更多关于 MCP 的内容，可以前往 帮助文档 查看。

支持创建「测试套件」

Apifox 推出了「测试套件」功能，支持添加单接口用例和场景用例，并可在「静态」与「动态」两种模式间切换：

静态模式用于精确指定需要执行的测试项，内容不会变动，且支持灵活调整测试步骤的顺序。

动态模式可通过规则自动筛选需执行的测试项。每次运行时，系统会实时扫描项目，将所有符合条件的最新用例纳入执行。此模式下，仅可整体删除或修改过滤条件，无法单独删除组内的某个动态项。

场景用例侧重于测试流程的编排，测试套件则聚焦于灵活高效的测试执行，两者并非互相替代，而是分层协作，面向不同的使用场景，结合使用可以满足自动化测试的多样化需求。

更多关于测试套件的具体教程，可以查看往期内容《 测试用例越堆越多？用 Apifox 测试套件让自动化回归更易维护 》。

测试报告全面重构，支持结构化展示

最新版本的 Apifox 对测试报告界面进行了全面重构，新版测试报告支持结构化展示所有测试步骤，让测试结果的层次关系更加清晰明了。用户可以快速定位每个测试步骤的执行情况和结果，从而更高效地分析测试问题，提升测试结果的可读性和分析效率。

调试能力持续升级

支持查看 HTTP 版本、TLS 协议等网络信息

更新 Apifox 后，开发者在调试接口时可直接查看 HTTP 版本、TLS 协议等详细网络信息，从而快速掌握接口请求的通信细节，有助于进行更精确的问题定位和性能分析。

同时，支持查看更详细的响应大小信息，包括 Body 和 Header 的大小，以及压缩前后的 Body 大小，便于判断 gzip 等压缩功能是否正常工作。

array 类型参数的子元素支持直接选择枚举值

调试接口时，如果 array 类型参数的子元素包含枚举值，用户可直接从列表中选择，无需手动输入，简化了配置流程，提升参数配置的便捷性与准确性，使接口调试更加高效流畅。

调试 SSE 接口时，支持 `\r\n` 换行符

Apifox 优化了 SSE 接口的调试体验。SSE 规范采用 \n\n 作为标准换行符，但一些实际业务中常用 \r\n （Windows 换行符） 进行分隔。Apifox 现已兼容并正确解析 \r\n 换行符，确保 SSE 流式数据能够以标准或非标准格式都能正确显示，帮助开发者更高效、准确地调试和验证 SSE 接口响应内容。

支持导入 Hoppscotch 的 Collection

Apifox 现已支持导入 Hoppscotch Collection 数据，帮助团队更便捷地将 Hoppscotch 项目迁移到 Apifox，进一步扩展了数据迁移的兼容性，降低迁移成本，提升团队协作的灵活性。

优化邀请他人加入项目的流程

Apifox 对项目成员邀请流程进行了优化，除了链接邀请和邮箱邀请外，还支持直接从团队成员列表中选择成员加入项目，并可在邀请时同步设置项目权限，大幅简化了成员管理流程，让团队协作配置更加便捷高效。

用户反馈优化

解决 MongoDB 数据库的密码包含特殊字符`%`时无法连接成功的问题

根据用户反馈，我们已修复 MongoDB 数据库连接中存在的问题：当数据库密码包含特殊字符 % 时，Apifox 现能正确处理并成功建立连接，进一步提升了数据库连接功能的稳定性和兼容性。

解决绑定了手机号的用户无法通过“忘记密码”功能重置密码的问题

现在通过"忘记密码"功能可以正常重置密码，确保用户在需要时能顺利找回账号访问权限，提升账户安全管理功能的完整性与可用性。

了解更多

当然，Apifox 产品团队为大家带来的新功能远不止以上这些：

优化了前后置操作的界面
优化了测试报告列表，支持结构化展示、筛选
支持复制测试套件的分享链接
支持调整测试套件静态步骤内资源的顺序
导入 OpenAPI/Swagger 数据时，支持 Query 类型的 HTTP 方法和 additionalOperation
优化了变量预览弹窗的触发时间，让其有一个合理的延迟
在付费页进行续费时，逻辑更合理与友好
解决在接口返回的响应数据上点击右键，没有 Copy JSONPath 等功能的问题
解决当根目录的可见性为内部时，WebSocket 接口仍被发布到公开在线文档的问题
解决未绑定支付方式的团队无法被正确转入组织的问题

同时，Apifox 提供企业私有化部署版本，通过本地化部署、客制化服务，协助企业进一步提升研发团队效能。

apifox

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能和更极致的使用体验！

测试用例越堆越多？用 Apifox 测试套件让自动化回归更易维护

Apifox — Wed, 21 Jan 2026 07:34:55 GMT

当项目中的接口测试用例和测试场景越积越多，单独管理和执行它们的成本会急剧上升。原本用于保障质量的自动化测试，自身反而成了维护的负担。

传统的维护方式是手动点选。当项目沉淀了大量用例和测试场景时，手动核对哪些该入库、哪些该回归，会成为沉重的体力成本。

Apifox「测试套件」通过动态模式解决了这个问题。它不再死板地记录 ID，而是保存一套筛选规则，例如按目录、标签、优先级等条件进行组合筛选。

在每次运行前，套件会根据筛选规则，自动组合所有符合规则的用例和测试场景。这意味着你只需专注于测试内容的编写和打标，新增的测试资产就会自动进入 CI/CD 流水线，真正实现无人值守的持续集成。

最终，所有执行项的结果会被汇总到一份聚合报告中，便于集中分析和定位问题。

创建并编排你的第一个套件

将 Apifox 更新到最新版本后，在「自动化测试」模块中，可以找到「测试套件」的分类。点击其右侧的 ... 按钮，选择「新建测试套件」。

在弹出的窗口中输入一个描述性的名称，配置相关的优先级或者标签，一个空的测试套件就创建完成了。

创建完成后，核心工作是向这个套件中添加内容。测试套件的内容可以是单个的「接口测试用例」，也可以是包含多个步骤的「测试场景」。

添加测试内容：静态与动态

点击「添加接口测试用例」或「添加测试场景」时，会看到「静态」和「动态」两种模式的选项。这两种模式决定了测试套件如何管理其包含的测试项，适用于不同的维护策略和测试目标。

静态模式，顾名思义，是精确地、不变地指定要执行的测试项。当你以静态模式勾选某些用例时，系统记录的是这些用例的唯一 ID。即使后续这些用例的源目录增加了新的用例，或者用例本身被移动，这个套件的执行范围也不会改变。它的确定性很高，确保了每次运行的内容完全一致。

动态模式则完全不同。它不记录具体的用例 ID，而是保存一套 “筛选规则”，例如 “某个目录下的所有用例” 或 “所有标签为「语义合法」的用例”。

又或者是 “所有标记为 P0 优先级的测试场景”。

在动态模式下，每次运行测试套件时，系统都会根据这套规则重新扫描整个项目，将所有当前符合条件的用例动态地纳入执行计划。这意味着，只要测试用例的属性（如所在目录、标签、优先级）符合规则，它就会被自动包含进来。

静态模式与动态模式：如何选择？

这两种模式没有绝对的优劣之分，而是服务于不同的管理需求。选择哪种模式，取决于你希望测试套件具备怎样的维护特性。

对于需要严格控制范围的专项测试，静态模式更可靠。而对于需要持续迭代、自动纳新的回归或冒烟测试，动态模式则能极大地降低维护成本。

为了更清晰地理解两种模式的差异，可以通过下表进行对比：

执行顺序与高级配置

添加完测试内容后，可以在编排列表中通过拖拽调整它们的执行顺序。

在执行项（测试场景）的右侧，可以对套件的运行行为进行更细粒度的控制。

例如，「遇到错误时」选项可以决定当某个步骤失败后是继续执行、跳过当前轮次还是立即终止整个运行。「循环次数」则可以将整个套件重复执行多次，用于简单的稳定性测试。这些配置让测试套件不仅仅是一个用例的集合，更是一个可控的执行流程。

运行测试套件

构建好测试套件后，下一步就是执行它。Apifox 提供了从本地手动运行到云端自动化执行的多种方式，以适应不同阶段和环境的需求。

本地可视化运行

最直接的运行方式是在 Apifox 客户端界面中，点击「运行」按钮。这种方式会从本地机器发起请求，适用于在开发和调试阶段进行小规模、快速的测试验证。在运行配置界面，可以临时切换「运行环境」，或设置在运行结束后发送通知。

运行完成后，Apifox 会生成一份本次执行的测试报告，并在界面中以可视化方式展示。报告中会按执行顺序列出每一个接口测试用例和测试场景的结果，清晰标识成功和失败状态，点击具体测试项可查看更详细的报告。

通过 CLI 运行

当测试规模较大，或者需要在无图形界面的服务器上执行时，Apifox CLI 是更高效的选择。它是一个命令行工具，可以将 Apifox 中的测试能力延展到任何终端环境。

要使用 CLI 运行，首先需要安装 Apifox CLI，并确保其版本为最新。完成安装或升级后，可以在测试套件的「CI/CD」标签页中找到自动生成的命令行：

将这条命令复制到终端中执行，即可在命令行看到与图形界面一致的测试过程和结果。

运行结束后，它还会在当前目录下生成一个 apifox-reports/ 文件夹，里面包含了 HTML 格式的详细测试报告。

通过 CLI 运行的方式是实现 CI/CD 的基础。可以将这条命令集成到 Jenkins、GitLab CI 或 GitHub Actions 的脚本中，在代码合并等关键节点自动触发回归测试。

通过定时任务运行

Apifox 内置了「定时任务」功能。在测试套件的「定时任务」标签页，可以新建一个任务，设置其运行周期和运行环境。

与本地运行不同，定时任务需要指定在「自托管 Runner」上执行。

Runner 是一个可以由团队自行部署在内网服务器上的轻量级执行程序。使用 Runner 可以解决本地机器关机或网络不通导致定时任务失败的问题，并利用服务器更强大的计算资源来执行大规模测试。

设置好定时任务后，Apifox 会在指定时间自动调度 Runner 执行测试套件，并将运行历史和报告上传至云端。同时，可以配置失败通知，一旦线上接口出现异常，相关人员就能第一时间收到告警信息，及时介入处理。

总结

通过静态与动态两种编排模式，你既可以精确控制专项测试的执行范围，也能让回归测试随业务迭代自动更新，无需反复手动维护。配合本地运行、CLI 集成和定时任务等多种执行方式，测试套件可以灵活嵌入开发流程的各个环节——从开发阶段的快速验证，到 CI/CD 流水线的自动化回归，再到生产环境的定时巡检。

更多关于测试套件的知识可以前往 Apifox 帮助文档查看。现在就去试试创建你的第一个测试套件，将现有测试内容进行编排，逐步构建可持续运行的自动化回归体系。

Apifox CLI + Claude Skills：将接口自动化测试融入研发工作流

Apifox — Wed, 14 Jan 2026 07:44:20 GMT

在这套工作流中，你只需要在终端里对 Claude Code 说一句话，例如：“用开发环境跑一下支付流程的测试”。

Claude Code 就会自动识别你的意图，定位对应的“测试场景”或“测试套件”来执行测试。测试完成后，它会对执行结果进行整理和解读。

这套流程由三个工具组成：

Apifox CLI： Apifox 的命令行工具。用于在终端中执行 CLI 命令，并生成测试报告。
Claude Code： Anthropic 推出的命令行 AI 助手。可以在终端操作文件、运行命令、执行脚本等。
Claude Skills： 也称 Agent Skills，是 Claude Code 的扩展功能。它可以定义 Claude 如何完成特定任务，相当于一份可执行的操作说明。

在这套流程中，Claude Code 负责理解自然语言指令，若“指令”匹配到本工作流中预置的 Claude Skills 后，就会自动执行 Apifox CLI 命令并分析执行结果。

这套流程能做什么

下面通过几个实际操作场景，直观了解这套工作流的使用方式：

执行单个测试

如果想执行特定的测试场景，可以直接指定。例如，在 Claude Code 输入：“帮我跑一下登录功能的测试，用开发环境”，测试完成后 Claude 会分析结果并给出总结。

如果测试失败，Claude 会分析失败原因。

查看所有可用测试

如果想知道有哪些测试场景或测试套件，可以问：“有哪些测试可以执行？”。Claude 就会运行相关的脚本，把所有测试列出来。

执行某个业务模块的所有测试

想执行某个业务模块的所有测试，例如想一次跑完支付相关的测试，可以说：“用测试环境跑一下支付相关的所有测试”。Claude 会自动找到所有相关测试文件并依次或者并行执行。

对比不同环境的测试结果

如果需要对比不同运行环境的测试结果，可以说：“用开发环境和测试环境跑一下登录功能的测试”。Claude 会在两个环境下执行测试，并帮你分析结果差异。

根据代码变更执行测试

当代码有更新时，可以让 Claude 只执行受影响的测试场景或测试套件。例如：“根据最近的代码变更，在开发环境跑一下受影响的接口测试”。Claude 会根据 Git 分析变更文件，并选择对应测试执行，节省时间和资源。

其它更多场景，需要你来探索......

下面将依次介绍 Apifox CLI、Claude Code 和 Claude Skills 的安装和构建方式，以及如何将它们组合使用，最终跑通这套工作流。

准备工作

环境要求

确保电脑上装了 Node 环境，可打开终端验证：

node -v
npm -v

安装 Apifox CLI

通过 npm 安装：

npm install -g apifox-cli

apifox --version

看到版本号说明安装成功。

可以到 Apifox 的「自动化测试 -> CI/CD」中，复制一个“测试场景”或者“测试套件”的 CLI 命令到终端执行，记得添加 Access Token。

看到测试输出就说明 Apifox CLI 能正常工作了。

💡 需要将 Apifox 客户端和 Apifox CLI 更新到最新版，才能使用最新的“测试套件”功能。

安装 Claude Code

通过 npm 安装：

npm install -g @anthropic-ai/claude-code

claude --version

首次运行需要登录：

claude

按照提示完成授权，需要 Claude 账号 （可以通过某鱼或一些中转站解决账号问题）。登录后会进入对话界面，试试问一些问题，Claude 会给出回答。

现在 Claude 还不知道怎么跑 Apifox 测试，接下来我们通过 Claude Skills 来教会它。

Claude Skills 的构建

理解 Skills 的工作原理

使用 Claude Code 时，你不需要手动指定要使用的 Skill。你只需要用一句话描述你想做的事，Claude 会自动选择合适的 Skill 来完成。

只要你输入的自然语言与某个 Skill 的描述相匹配，Claude 就会加载该 Skill，并按照其中定义的流程执行任务。

步骤 1：创建 Skill 目录

Skills 的配置文件统一放在 .claude/skills/ 目录下，每个 Skill 对应一个独立的子目录。

在这里，我们在项目根目录下，为 Apifox 自动化测试创建一个最小可用的 Skill 目录：

mkdir -p .claude/skills/apifox-tests

执行完成后，目录结构如下：

.claude/skills/apifox-tests/

后续我们会在这个目录中，逐步添加 Skill 的入口文件和执行脚本等内容。

步骤 2：创建 SKILL.md

每个 Skill 都需要一个 SKILL.md 文件，用来说明当这个 Skill 被匹配到时，Claude 应该如何一步步完成任务。

SKILL.md 以 --- 包裹的 YAML 元信息开始，其中 name 和 description 是必需字段。

description 尤其重要，它用于帮助 Claude 判断在什么场景下应该启用这个 Skill，所以这里要根据你的业务写触发条件。

在 YAML 之后的 Markdown 内容中，则用于描述这个 Skill 被启用后，Claude 具体应该怎么做，包括判断逻辑、执行步骤、引用的脚本、以及需要遵循的约束规则。

下面是一个可直接使用的 SKILL.md 示例，用于定义 Apifox 自动化测试的执行流程：

---
name: apifox-tests
description: 执行和解读 Apifox 自动化测试。触发场景：(1) 修改代码后需要验证接口可用性 (2) git commit/push 前的接口检查 (3) 发布版本前的回归测试 (4) 用户明确要求运行 Apifox 测试，或用具体环境跑相关测试 (5) 合并到 main 分支前的自动化检查。选择合适的测试场景或者测试套件，执行测试并解释结果，但不修改测试或命令本身。
---

# Apifox Tests

执行 Apifox 自动化测试并解释结果。

## 工作流程

1. **选择测试**：

- 如果用户在对话中明确提供了：
  - 测试文件路径
  - 测试文件名
  - 或清晰可唯一匹配的测试名称
- 直接使用该测试，不再进行自动选择
- 若信息不明确，应优先通过运行 `node ./.claude/skills/apifox-tests/scripts/list-tests.js` 脚本来快速获取所有的测试文件路径及描述。
- 避免在庞大的项目目录中进行盲目的全局搜索，直接定位到该 Skill 专用的测试文件目录 `tests/`。

2. **多测试执行规则**- 默认只执行一个测试，但需给出是否批量执行的选择
- 如果用户明确表示：
  - “跑这几个”
  - “全部跑一遍”
- 则进入**批量执行模式**批量执行模式下：
- 明确列出将要执行的测试列表
-**询问执行方式**：让用户选择 “按顺序执行” (更易读) 或 “并行执行” (速度快)。
  - **按顺序执行**：逐个运行测试并即时分析，适合调试。
  - **并行执行**：同时启动多个测试（使用 `&` 结尾或脚本并发），适合快速回归，但日志可能会交织。
- 请求用户确认执行方式及测试列表（是 / 否）
- 按选择的方式执行测试
- 最终汇总或依次解释每个测试的结果

3. **确认环境**：
- 支持的环境包括：
  - `dev`
  - `test`
  - `prod`
- 如用户未明确指定环境：
  - 列出上述环境名
  - 让用户确认使用哪一个

4. **执行测试**：
- 在以下信息明确后执行测试：
  - 测试文件路径
  - 环境名（dev / test / prod）
```bash
node ./.claude/skills/apifox-tests/scripts/run-cli.js <测试文件路径> <环境名>
```

5. **解释结果**：分析 Apifox CLI 输出，解释失败原因

## 失败处理

- 不修改测试文件
- 不修改执行命令
- 基于测试名称、接口语义和 CLI 输出解释失败原因

步骤 3：补充 Skill 所需的支持文件

在前面的步骤中，我们已经创建了 SKILL.md，用于定义这个 Skill 的触发条件和整体执行流程。

在此基础上，其余文件都只是对 SKILL.md 的补充，当流程中需要其它信息，比如运行环境、执行命令或测试定义时，再按需引入对应的文件即可。

最终，这个 Skill 的目录结构如下：

.claude/skills/apifox-tests/
├── SKILL.md              # Skill 入口，定义触发条件和整体流程
├── env/                  # 运行环境配置（如 dev / test / prod），用于区分不同测试环境
│   ├── dev.env           # 开发环境
│   ├── test.env          # 测试环境
│   └── prod.env          # 生产环境
├── scripts/              # 执行脚本（被 SKILL.md 调用）
│   ├── list-tests.js     # 列出 tests 目录下的所有测试
│   └── run-cli.js        # 负责组装并执行 Apifox CLI 命令
└── tests/                # 测试定义（每个文件对应一个测试场景或测试套件）
    ├── 支付流程.md        
    └── 退款流程.md

下面分别介绍这些支持文件的作用和示例。

环境配置（env）

env/ 目录用于存放不同运行环境对应的变量配置，例如 Apifox 的访问令牌 （Access Token）和环境 ID。

将环境 ID 抽离为变量，可以让我们在不改任何命令或脚本的情况下，快速切换测试运行环境 （如开发 / 测试 / 生产）。

例如，在 env/ 目录下创建 dev.env 文件：

APIFOX_ACCESS_TOKEN=APS-你的访问令牌
APIFOX_ENV_ID=你的环境ID

如果需要支持多个环境，可以按照同样的方式创建：

*test.env

prod.env

……

每个文件只需要维护对应环境的变量即可。

环境 ID 对应的是 Apifox CLI 命令中 -e 参数后面的数字，每一个运行环境 （如开发、测试、生产）在 Apifox 中都会有一个唯一的环境 ID。

💡 env/ 目录的 .env 文件包含访问令牌，是敏感信息，不能提交到 Git。

执行脚本（scripts）

scripts/ 目录用于存放可直接执行的脚本，负责把「测试定义」转换为实际可运行的 Apifox CLI 命令，并完成环境变量注入与执行。

本文中的 Skill 选择使用 Node.js，主要基于两个考虑：

Apifox CLI 本身依赖 Node.js 直接复用同一运行环境，无需额外准备 Python 等运行时。

降低上下文负担，减少 tokens 消耗 将“命令解析、变量注入、执行逻辑”放在脚本中完成，可以避免让 Claude 在对话中反复拼装完整 CLI 命令。

如果你对脚本不熟悉，也可以选择不使用，而是在 SKILL.md 中直接让 Claude 组装并执行 CLI 命令，只是上下文成本会更高一些。

在 scripts/ 目录下创建 run-cli.js，它的核心职责是：

从指定的 Markdown 测试文件中提取 Apifox CLI 命令

根据选定的环境（如 dev / test）加载对应的 .env 文件

注入环境变量后执行测试

可直接使用的示例脚本如下：

import fs from "fs";
import path from "path";
import { execSync } from "child_process";
import dotenv from "dotenv";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// args
const mdPath = process.argv[2];
const envName = process.argv[3] || "local";

if (!mdPath) {
    console.error("❌ 缺少测试 md 文件路径");
    process.exit(1);
}

// env 路径：始终相对 skills 本身
const envPath = path.join(__dirname, "..", "env", `${envName}.env`);

if (!fs.existsSync(envPath)) {
    console.error(`❌ 未找到环境配置：${envPath}`);
    process.exit(1);
}

dotenv.config({ path: envPath });

// 读取 md
const content = fs.readFileSync(mdPath, "utf-8");
const match = content.match(/```bash([\s\S]*?)```/);

if (!match) {
    console.error("❌ 未找到 bash 命令块");
    process.exit(1);
}

let command = match[1].trim();

// 变量替换
command = command
    .replaceAll("$APIFOX_ACCESS_TOKEN", process.env.APIFOX_ACCESS_TOKEN)
    .replaceAll("$APIFOX_ENV_ID", process.env.APIFOX_ENV_ID);

console.log(`▶ Running (${envName})`);
console.log(command);

// 执行
try {
    execSync(command, { stdio: "inherit" });
} catch (e) {
    // Apifox CLI 在测试失败时会返回退出码 1
    process.exit(1);
}

同样在 scripts/ 下创建 list-tests.js，用于：

递归扫描 tests/ 目录
查找所有 Markdown 测试文件
提取首行描述信息
输出当前所有可用的 Apifox 自动化测试列表

可直接使用的示例脚本如下：

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const testsDir = path.join(__dirname, "..", "tests");

function scan(dir, relativePath = "") {
    const items = fs.readdirSync(dir, { withFileTypes: true });
    
    for (const item of items) {
        const fullPath = path.join(dir, item.name);
        const relPath = path.join(relativePath, item.name);
        
        if (item.isDirectory()) {
            scan(fullPath, relPath);
        } else if (item.name.endsWith(".md")) {
            try {
                const content = fs.readFileSync(fullPath, "utf-8");
                const firstLine = content.split("\n")[0].trim();
                const description = firstLine.startsWith(">") 
                    ? firstLine.replace(/^>\s*/, "").trim() 
                    : "无描述";
                const displayPath = path.join("./.claude/skills/apifox-tests/tests", relPath);
                console.log(`[${displayPath}] - ${description}`);
            } catch (err) {
                console.log(`[${relPath}] - (无法读取内容)`);
            }
        }
    }
}

console.log("🔍 可用的 Apifox 自动化测试列表：");
if (fs.existsSync(testsDir)) {
    scan(testsDir);
} else {
    console.log("❌ 未找到 tests 目录");
}

测试定义（tests）

tests/ 目录用于存放测试文件，采用 Markdown 编写。

设计原则：一个 Markdown 文件对应一个 Apifox 测试场景或测试套件。你可以直接复用 Apifox 自动化测试中已有的目录结构、测试场景或测试套件名称，以及描述信息。

每个 Markdown 文件只需包含两部分内容：一段简短的测试说明，以及一条可直接执行的 Apifox CLI 命令。

Apifox CLI 命令里的 Access Token 和 -e 参数后面的环境 ID，分别用 $APIFOX_ACCESS_TOKEN 和 $APIFOX_ENV_ID 代替，并统一在 .env 文件中配置，这样既可以避免 token 泄露，也能灵活切换运行环境。一个登录鉴权-认证流程.md文件的内容示例：

> 验证登录、刷新 token、登出等核心接口是否可用。

```bash
apifox run --access-token $APIFOX_ACCESS_TOKEN -t 5564xxx -e $APIFOX_ENV_ID -n 1 -r html,cli
```

到这一步，我们的 Skills 算是构建完了，可以参考一下结构，对比一下与你的有什么不同：

在 Claude Code 中使用

配置完成后，在终端控制台运行 claude 命令进入项目目录。Claude 会自动扫描 .claude/skills/ 目录，发现 apifox-tests Skill。

你也可以先用 /skills 命令查看已加载的 Skill。

然后，可以试着说一句自然语言指令，例如：“帮我跑一下退款流程的测试，用测试环境 ”。

Claude 会理解你的意图，找到对应的测试文件并执行测试。在执行过程中，你会看到 Apifox CLI 的输出；测试完成后，Claude 会对结果进行分析并给出总结。

整个流程概述起来就是，你用自然语言描述需求，Claude 理解意图并调用脚本，脚本执行 Apifox CLI 命令，Claude 分析结果并反馈给你。

总结

本文介绍了如何通过 Claude Code、Apifox CLI 和 Claude Skills 构建自动化测试工作流。核心思想是让 Claude 成为你和工具之间的桥梁。你用自然语言描述需求，Claude 理解意图后调用脚本，脚本执行具体工作，Claude 把结果整理成易读的形式反馈给你。

要让这套方案真正发挥作用，需要根据项目特点调整配置。比如测试的组织方式、环境的管理策略、结果的分析逻辑等。好在这套方案各个部分都可以定制，可以根据需要添加新功能或修改现有逻辑。

如果你的团队经常需要执行接口测试，希望让这个过程更自动化、更智能，这套方案值得一试。初期需要花时间配置和熟悉，但一旦建立起来，能显著提升工作效率。随着使用深入，你会发现更多可以优化的地方，让整个工作流越来越顺畅。

可以前往 Apifox 帮助文档，查看更多功能说明和操作指南。如有任何问题，欢迎在 Apifox 用户群与我们交流沟通。

Apifox 12 月更新｜ AI 生成用例同步生成测试数据、接口文档完整性检测、设计 SSE 流式接口、从 Git 仓库导入数据

Apifox — Tue, 30 Dec 2025 06:04:30 GMT

Apifox 新版本上线啦！看看本次版本更新主要涵盖的重点内容，有没有你所关注的功能特性：

AI 能力再进化
AI 生成测试用例时，支持同时生成匹配用例的测试数据
支持通过 AI 进行接口文档完整性检测
新增支持多个 AI 模型供应商
API 设计与 OpenAPI 规范兼容
设计 API 时，支持 SSE 流式响应及 AI 大模型接口
支持设定 2XX、4XX、5XX、default 等特殊状态码
API 调试能力扩展
支持为环境中各服务配置通用网络代理（HTTP / SOCKS5）
调试 Socket.IO 接口时，支持发送空消息和无参数的消息
支持在输入框直接编辑引用的变量名、动态值表达式
在线文档持续升级
支持自定义背景图案、目录树宽度、多级导航
支持 Algolia 的「Ask AI」功能
导入/导出功能进化
支持从 Git 仓库导入数据
支持导入/导出「响应组件」
用户反馈优化
编辑 Markdown 时，编辑区与预览区同步滚动
解决 Query 参数值为空，选择「不添加等号」时仍会添加等号的问题
解决导入 OpenAPI/Swagger 数据时，如果指定了目录，数据模型会被重复导入的问题

将 Apifox 更新至最新版，一起开启全新体验吧！

AI 能力再进化

AI 生成测试用例时，支持同时生成匹配用例的测试数据

升级至最新版 Apifox 后，AI 在生成测试用例的同时，会自动生成与用例匹配的测试数据，从而减少手动准备数据的工作量，确保测试数据精准贴合用例场景，提升测试用例的完整性与实用性。

同时，也支持手动为每个测试用例添加或修改对应的测试数据，帮助团队便捷、清晰地管理测试资源。

支持通过 AI 进行接口文档完整性检测

Apifox 新增了「接口文档完整性检测」功能，可通过 AI 检测分析接口文档可能存在的信息缺失、描述模糊或规范性不足等问题，帮助团队快速定位潜在问题并提升文档质量与完整性，从而建立更高标准的 API 文档规范。

新增支持多个 AI 模型供应商

Apifox 扩展了 AI 模型供应商的支持范围，新增支持月之暗面 Kimi K2 系列、智谱 GLM-4.7 和 MiniMax M2.1 系列模型，为用户提供更丰富的 AI 模型选择，帮助团队根据具体需求挑选最适合的 AI 能力。

API 设计与 OpenAPI 规范兼容

设计 API 时，支持 SSE 流式响应及 AI 大模型接口

最新版本的 Apifox 新增对 SSE 流式响应和 AI 大模型接口设计的支持，开发者可为 string 类型字段配置「内容结构（Content Schema）」，从而能够更精准地定义流式数据的响应结构，为流式数据与 AI 接口提供了完善的文档规范解决方案。

支持设定 2XX、4XX、5XX、default 等特殊状态码

Apifox 扩展了 API 设计中的状态码支持范围，能够兼容 OpenAPI/Swagger 规范中定义的特殊状态码，如 2XX、4XX、5XX 和 default 等，从而更精确地定义接口的响应行为，灵活处理不同类型的响应场景，为开发者提供更加精细和标准化的接口设计体验。

API 调试能力扩展

支持为环境中各服务配置通用网络代理（HTTP / SOCKS5）

Apifox 现在支持为环境中每个服务的前置 URL 配置通用网络代理，兼容 HTTP 和 SOCKS5 两种协议。用户可以更好地处理不同网络环境下的接口访问需求，特别适合需要通过代理访问特定服务的场景，从而提升环境管理的灵活性和适应性。

调试 Socket.IO 接口时，支持发送空消息和无参数的消息

升级至最新版本的 Apifox 后，调试 Socket.IO 接口时，支持发送空消息和无参数消息，使开发者能够全面模拟和测试实时通信的各种场景。

支持在输入框直接编辑引用的变量名、动态值表达式

现在，用户可以直接在输入框内编辑引用的变量名、动态值表达式，无需切换到其他界面即可完成调整，从而提升配置效率和操作便捷性。

在线文档持续升级

支持自定义背景图案、目录树宽度、多级导航

在线文档新增多项个性化设置，支持自定义背景图案及颜色、调整目录树宽度和配置多级导航，让用户能够根据个性化需求，打造独特的文档风格和布局，构建个性化舒适的文档展示方式。

支持 Algolia 的「Ask AI」功能

在线文档新上线了 Algolia 的「Ask AI」功能，支持通过 AI 智能问答快速获取所需文档信息。用户可以在搜索框中直接向 AI 提问，快速获取关于文档的准确解答，使 API 文档的查阅和理解变得更加便捷和高效。

导入/导出功能进化

支持从 Git 仓库导入数据

Apifox 更新至最新版本后，支持从 GitHub、GitLab 仓库等主流代码托管平台导入 OpenAPI/Swagger 文件，方便团队高效同步并集中管理分散在各平台的 API 文档，简化文档集成流程，全面提升团队协作效率。

支持导入/导出「响应组件」

现在导入/导出 OpenAPI/Swagger 数据时，能够同时导入/导出响应组件，确保团队可以正确复用与共享标准化响应定义，提升 API 文档的一致性和维护效率。

用户反馈优化

编辑 Markdown 时，编辑区与预览区同步滚动

根据用户反馈，Apifox 优化了 Markdown 编辑体验。当左侧编辑区域滚动时，右侧预览区域将自动同步滚动，使文档编辑与预览更加流畅自然，提升使用体验。

解决 Query 参数值为空，选择「不添加等号」时仍会添加等号的问题

当 Query 参数为空且选择「不添加等号」选项时，Apifox 现已能够正确处理，避免错误添加等号，确保参数构建准确，符合用户实际配置需求。

解决导入 OpenAPI/Swagger 数据时，如果指定了目录，数据模型会被重复导入的问题

我们修复了用户反馈的问题：在导入 OpenAPI/Swagger 数据时，若指定了目录，数据模型将不会重复导入，从而确保导入过程更加准确，避免生成冗余数据，保持文档结构清晰高效。

了解更多

当然，Apifox 产品团队为大家带来的新功能远不止以上这些：

密钥库支持 Client Credentials 授权模式
导出 Apifox 格式数据时，包含接口的测试用例
导出 Apifox 格式数据时，包含 WebSocket 和 Socket.IO 接口的前置 URL
优化了 AI 相关功能的报错信息，更清晰明确
提升 AI 生成测试用例的指令遵循效果
配置 AI 模型供应商时，可以选择 DeepSeek V3.2 Exp 系列新模型
优化了在环境管理配置前置 URL 的交互
优化了自动化测试编排模式的交互
解决新建接口后发送请求，如果请求未成功，就无法保存接口的问题
解决导入数据时选择智能合并，参数的示例值被错误覆盖的问题
解决在网页版 App 添加 Runner 时，如果服务器是 http:// 协议就无法保存的问题
解决测试用例 GraphQL 请求体高度无限增长的问题
解决 AI 生成测试用例抽屉层级的问题
解决调试 Socket.IO 接口时，选择 JSON，无法正常发送 0、false 等内容的问题

除了新增功能，我们也对产品细节和使用体验进行了优化，具体修改内容可前往 Apifox 更新日志查看。

查看更新日志

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能和更极致的使用体验！

可以前往帮助文档查看更多功能使用说明和操作，有任何问题欢迎在 Apifox 用户群与我们交流沟通。

AI 参与下的 Apifox 接口自动化测试实践

Apifox — Thu, 18 Dec 2025 02:50:37 GMT

在 AI 逐步参与接口开发和测试的当下，自动化测试的门槛正在被不断拉低。很多过去需要反复手动操作、人工造数据的事情，现在都可以交给 AI 来处理，而 Apifox 在接口测试这件事上，也正在发生类似的变化。

在 Apifox 中，自动化测试主要围绕两类使用方式展开：「单接口测试」和「测试场景」。

如果你没有看到「单接口测试」这个模块，那是因为 Apifox 版本较旧，更新到最新版即可。

「单接口测试」展示的是「接口管理」中的所有 HTTP 接口，但功能更加聚焦，只包含测试用例、测试报告和文档三个部分，无法编辑接口本身。这样的设计可以让测试人员专注于测试用例的创建和执行。

「测试场景」则是把多个接口或用例串联起来，设置接口调用顺序和数据传递关系，用来还原一次完整的业务流程。

不论是单接口测试，还是测试场景，在 AI 的参与下，都能让接口测试逐步过渡到更自动化、更可复用的执行方式。接下来，我们就分别看看，这两种测试方式在实际使用中能帮你解决的问题。

单接口的自动化测试

单接口的自动化测试关注的是接口本身是否稳定、输入输出是否符合预期。每个测试用例都是独立执行的，重点在于把单个接口在不同数据下验证清楚。

AI 生成测试用例

在「单接口测试」模块下打开任意接口，点击「AI 生成用例」后，AI 会根据接口参数和响应结构自动生成一组测试用例。

如果你只想生成特定的用例，也不必勾选默认类型，只要把需求直接描述给 AI，测试用例就会生成。例如，可以让 AI 生成一条“登录成功并提取 token”或“根据已有参数生成签名字段 sign 并发送”的测试用例。

更详细的描述方式，可以明确已知条件和规则，例如：

为这个接口生成一条“正向”的测试用例。

接口需要一个签名参数 sign，签名规则如下：
1. 取请求中所有非空参数（不包含 sign），按参数名 ASCII 顺序排序，按 key=value 拼接，用 & 连接，并在末尾加上密钥 SECRET_KEY。
2. 对拼接后的字符串进行 MD5 加密并转为大写，作为 sign 的值。

测试用例要求：
1. 发送请求前，前置脚本生成 sign，要有注释。
2. 将 sign 加入请求参数中发送。

这样一来，AI 会完全按照你的规则生成用例，而不会出现遗漏或理解偏差。

测试数据的生成

在生成测试用例的同时，AI 还会为不同类型的用例准备对应的测试数据集，用来覆盖多种真实输入情况。

在正常业务场景的用例中，测试数据通常由多组语义上有效的参数值组成。例如在登录接口的测试中，虽然都是合法的邮箱和密码，但数据集中会包含多种常见邮箱写法，比如带点号、带加号、数字邮箱或企业邮箱等，用来验证接口在正常使用场景下的兼容性和稳定性。

而在异常或边界场景的测试用例中，测试数据则会刻意构造不符合规则的输入。例如「使用无效的邮箱格式登录，期望返回 400 错误码」这一类用例中，数据集中会包含缺少 @ 符号、缺少域名、包含空格等不同形式的非法邮箱，用来验证接口是否能够正确识别并拦截异常请求。

测试数据的引用

在测试用例中，你可以通过 {{变量名}} 的方式引用这些测试数据，将变量插入到请求参数、请求体等位置。测试执行时，Apifox 会从数据集中依次取值并发起请求，从而在不重复编写用例的情况下，用不同数据多次验证同一个接口。

批量执行与测试报告

当用例和对应的测试数据都准备好之后，你可以选择多个测试用例一起执行。每个用例都会按照各自的配置独立运行，执行结果最终会统一汇总在测试报告中，方便整体查看。

不过，在真实的业务中，接口往往不是孤立存在的。当一次请求的返回结果，需要作为下一次请求的输入时，测试的关注点也就从“一个接口”转向了“一整条调用链”。这时候，就需要用到「测试场景」了。

测试场景

在真实的业务中，一个接口往往很难单独完成任务。比如登录之后才能下单，下单成功后才能查询订单详情，前一个接口的返回结果，常常会成为下一个接口的输入。这类依赖关系，用「单接口测试」很难完整覆盖。

「测试场景」关注的不再是某一个接口是否返回正确，而是一整条调用链在串联执行时，是否能够按预期走通。

把接口串成流程

在 Apifox 中，新建一个测试场景后，你可以将多个接口或已有的用例按顺序加入进来，明确每一步的执行顺序。

在流程中传递数据

当接口之间存在依赖关系时，测试场景允许你把前一步接口的返回数据，作为变量传递给后续步骤使用。比如“创建订单”接口返回的 id，可以被直接用于后续的查询或更新操作。

这种数据传递并不需要额外编写代码，而是通过变量引用的方式，把接口之间的上下游关系清晰地表达出来。

用例缺少时怎么办

在编排测试场景的过程中，往往是先把一条主流程跑顺的。比如“登录 → 创建订单 → 查询订单”，每一步对应一个已经存在的测试用例。

但在实际编排时，你可能会发现一个很现实的问题：流程里的某一步，其实还没有现成的测试用例可以直接用，或者现有用例不完全符合流程需求。

例如登录步骤，你不仅关心“是否成功”，还需要把返回的 token 提取为环境变量，供后续接口使用。但现有单接口测试用例可能只做了基础登录校验，没有配置 token 提取。

如果你不熟悉如何把返回字段提取成变量，也不懂脚本的写法。这时可以先暂停测试场景的编排，切换到该接口的「单接口测试」页面，直接把需求交给 AI，比如说明：“生成一条登录成功后提取 token 并保存为环境变量的测试用例，并包含必要的断言”。

如果需要更可控的测试用例，可以在「高级设置」里启用分步生成。

启用后，会先生成用例列表（含用例名称和描述），你可以人工修改并确认无误，再生成完整的用例详情数据。

生成后回到测试场景，这条用例就可以直接作为登录步骤使用，后续接口通过「动态值」引用 token，流程就可以继续往下编排。

如果需要在「测试场景」中使用测试数据，也可以先在「单接口测试」里让 AI 生成带“测试数据”的用例，然后通过「批量编辑」把 CSV 格式的数据集复制到测试场景中，这样子造数据就方便了很多。

通过这种方式，测试场景始终围绕“主流程怎么走”来搭建，而 AI 的作用，则扮演了随用随补的角色。哪里缺一步，就在对应接口通过 AI 生成对应的用例，然后立刻接回流程。

总结

AI 并没有改变接口测试本身要验证什么，而是降低了开始和补齐测试的成本。

在“单接口测试”阶段，它主要解决的是用例生成慢、覆盖不全的问题，让测试可以更快进入验证阶段，而不是停留在准备数据和写用例上。

当测试进入“测试场景”阶段，关注点从单个接口的正确性，转向接口之间在真实调用顺序下是否能够正常协作。

在这个过程中，测试用例并不需要一次性准备齐全。随着测试场景逐步搭建，可以随时回到单接口测试，通过 AI 补充当前场景真正需要的用例，再继续编排测试步骤。这种方式减少了无效用例的提前投入，也少一些 credit 的消耗。

整体来看，Apifox 将单接口测试、测试场景和 AI 能力放在同一条工作流中，把接口测试中最容易卡住的几个环节（写用例、准备数据、串联流程）都放到了可操作的位置上。

如果你之前对自动化测试的印象还停留在“配置复杂、上手成本高”，不妨直接在 Apifox 里从一个接口开始，生成几条用例，跑一次测试场景，很快就能感受到这种方式在实际使用中的差别。

可以前往 Apifox 帮助文档，查看更多功能说明和操作指南。如有任何问题，欢迎在 Apifox 用户群与我们交流沟通。

如何在 Apifox 中借助 AI 设计一份规范的接口文档？

Apifox — Wed, 10 Dec 2025 02:48:05 GMT

通过 Apifox 的 IDEA 插件，或者一些 Swagger 插件，你可以很方便地将代码中的 API 生成接口文档，这解决了从零开始写文档的问题。

不过，即使接口写完了，文档也生成了，心里可能还是会有点不踏实，或许会斟酌这个接口设计得怎么样？文档搞得够不够规范？还有没有什么地方能再优化一下？

特别是在团队协作中，你会希望自己写的接口文档能让其他小伙伴一看懂。命名是否清晰、信息是否完整，这些都会直接影响他们使用你接口时的体验。

Apifox 近来陆续上线了几个 AI 功能，专门帮你在这个阶段进一步优化接口文档。不管是完善现有的接口信息，还是从其他地方导入已有的接口文档，AI 都能给你一些实用的建议。

下面我们就来看看，如何在 Apifox 中借助 AI 设计一份更规范的接口文档。在开始之前，请确认你已经将 Apifox 更新到最新版，并已开启 AI 功能和配置 AI 模型。

从现有文档开始导入

有时候你需要把其他地方的接口文档迁移到 Apifox 中。如果文档是标准格式，Apifox 本身已经支持多种导入方式：可以通过 IDEA 插件扫描代码中的接口，也可以导入 OpenAPI/Swagger 文件，还支持从 Postman 等其他工具迁移。

但也有一些情况下，你手头的文档可能不是这些标准格式。比如团队之前用 Markdown 记录接口，或者在 Word 文档里整理了一些字段说明，甚至是在聊天记录或邮件里找到的接口定义。这些非标准格式的内容，一个个字段录入想想都头大。

所以在这种情况下，如果想要轻松一点，就可以用「AI 辅助参数修改」功能来帮忙录入。假设你有一段这样的 Markdown 内容：

| name       | desc                                          | type      | required |
| ---------- | --------------------------------------------- | --------- | -------- |
| usePaging  | 是否启用分页                                    | boolean   | true     |
| offset     | 起始位置（启用分页时必填）                        | int       | false    |
| pageSize   | 每页数量（启用分页时必填）                        | int       | false    |
| minPrice   | 最低价格（单位：分）                             | int       | false    |
| maxPrice   | 最高价格（单位：分）                             | int       | false    |
| brand      | 品牌编码                                       | string    | false    |
| categoryId | 商品分类 ID                                    | int       | false    |
| sortRule   | 排序方式：1→ 销量优先 2→ 价格升序 3→ 价格降序    | enum(int) | false    |
| keyword    | 搜索关键词（模糊匹配商品名）                      | string    | false    |

你只需要把这里的参数内容复制过来，然后告诉 AI：“帮我把这些内容转换成接口参数，注意类型和必填项”。AI 会自动识别字段名、类型、是否必填、描述等信息，并转换成 Apifox 的标准数据结构，就算里面包含枚举，也会自动整理成枚举类型。

AI 帮你完善细节

导入基本信息后，接下来就是完善细节了。

如果你拿捏不准一个字段的命名，可以使用「AI 命名」功能。AI 会结合接口上下文和接口设计规范，给出更准确的命名建议。

字段描述或中文名称也可以交给 AI 来补全，自动生成更清晰、完整的说明。

Mock 数据的填充也是 AI 的强项。很多时候我们知道字段的含义，但不知道应该提供什么样的示例值。AI 会根据字段类型和描述，自动生成合理的示例数据。

完整性检查避免遗漏

文档完善得差不多时，心里往往还是会有些不确定，可能会觉得有没有关键的信息还没补全？这时候就可以用 Apifox 的「接口文档完整性检测」功能，来检查文档中是否存在遗漏的地方。

AI 会扫描你当前接口的接口文档，从多个角度检查可能的遗漏。检测完成后，会生成一份详细的报告，接口文档的每个检测内容都会进行打分。

报告里不只是建议你做什么，还会给出为什么这么做的原因。比如你写了成功响应的格式，但没有描述可能的错误情况；你提供了基本的字段说明，但缺少使用限制或格式要求。

你可以根据报告里的建议来完善接口文档。

规范性检查保证一致性

除了完整性之外，接口文档的规范性同样重要。同一个接口中，命名风格应该统一，字段类型定义要准确，响应结构要合理，这些细节对文档的可读性和可维护性影响很大。

Apifox 的「接口规范性检测」会从多个维度审查你的接口文档。它会检查命名是否一致，如果有些字段用了动词，有些用了名词，AI 会建议统一使用其中一种风格。

它也会检查字段定义的规范性，例如字段命名是否混用了大小写风格、是否同时出现下划线和驼峰、是否存在不一致的缩写方式等等，并给出相应的调整建议。

总结

完善以及规范接口文档是非常重要的，「AI 生成测试用例」也依赖接口文档的信息，文档越完整、越规范，AI 生成的用例就会越准确、越丰富。

你不需要一次性把所有 AI 功能都用上，也不需要完全改变现有的工作习惯。

整个过程是渐进式的。你可以从导入现有文档开始，然后逐步使用 AI 功能来完善和优化。当你对某个建议不确定时，可以先保持原样，等有更多上下文信息时再决定是否采纳。

随着使用次数的增加，你会发现自己对接口文档规范的理解在不断加深。AI 的建议不只是帮你解决当前的问题，更重要的是在潜移默化中培养更好的文档编写习惯。

以上的这几个 Apifox 的 AI 功能，本质上是降低了写规范文档的门槛。它让你在不增加太多工作量的前提下，得到更高质量的文档。每次使用 AI 功能，都是在学习更好的文档编写方法，所以，快去用起来吧！

可以前往 Apifox 帮助文档，查看更多功能说明和操作指南。如有任何问题，欢迎在 Apifox 用户群与我们交流沟通。

如何通过抓包工具快速生成 Apifox 接口文档？

Apifox — Wed, 03 Dec 2025 02:37:17 GMT

Apifox 作为 API 协作与管理平台，支持导入各种格式的接口数据。无论是 OpenAPI/Swagger、Postman Collection、HAR 文件，还是 cURL 命令，基本上主流的接口数据格式都能直接导入。

不过在许多实际项目中，最大的问题往往不是怎么导入接口数据，而是没有现成的接口数据可供 Apifox 导入。一些老项目可能从未维护过接口文档，也没有 OpenAPI/Swagger 文档可用。

这时候，如果想要快速补齐项目缺失的接口文档，或者生成测试用例，让测试人员能够基于真实数据快速起步。那么通过流量录制（抓包）工具来获取接口数据，应当是最快捷的解决方案。

通过抓包工具录制应用的 HTTP/HTTPS 流量，筛选后导出 HAR 或 cURL 格式的文件，再导入 Apifox，就可以快速生成接口文档，为后续的接口测试提供基础。

图片由 Nano Banana Pro 生成

可以进行流量录制的工具有很多，本文以 Charles Proxy 为例来演示具体操作，你也可以使用 Proxyman、Fiddler 等，或者直接使用浏览器自带的开发者工具进行抓包，核心流程大同小异。

Charles 安装与基础配置

Charles 提供 30 天免费试用，你可以从官网下载最新版本来安装。

首次启动 Charles 时，可能会询问是否自动配置系统代理。建议选择「Grant Privileges」授予权限即可，这样 Charles 就能自动捕获系统的 HTTP 流量了。

为了能够抓取 HTTPS 流量，需要安装 Charles 的根证书。点击菜单栏的「Help → SSL Proxying → Install Charles Root Certificate」，macOS 系统会打开钥匙串访问应用，搜索并找到 Charles Proxy 证书，双击后将信任设置改为 “始终信任” 即可。

Windows 系统需要在安装证书时安装到 “受信任的根证书颁发机构” 存储区。

证书安装后，接着启用 SSL 代理。在 Charles 菜单栏选择 Proxy → SSL Proxying Settings，勾选 “Enable SSL Proxying” 选项。

在列表中添加需要抓取的域名（Host）和端口（Port 443），也可以使用 * 监听所有域名。

配置完成后，Charles 就可以捕获完整的 HTTP/HTTPS 请求和响应了。

如果你不清楚应用具体使用了哪些域名，可以先随便操作应用，再观察 Charles 会话列表中 “Encrypted” 下的请求，记下对应的域名后，再把它们添加到 Charles 的 SSL 代理设置里即可。

录制应用的 API 流量

启动需要分析的应用或者网页，操作各种功能，如登录、查询数据、提交表单或上传文件。Charles 左侧会话树会实时更新请求，按域名和 URL 分组。

选中某个具体的请求后，右侧面板会显示请求的基本信息和响应内容。Contents 选项卡里会将 JSON 等响应折叠成树状结构，方便快速理解数据结构和字段。

筛选和导出接口

录制完成后，你可能会发现捕获到的请求非常多。除了真正的 API 接口调用，还有各种静态资源请求、第三方服务调用等等。这时候需要进行筛选，只保留我们关心的接口。

你可以右键点击域名或路径，选择 “Focus”，Charles 会只保留该节点下的请求。方便专注分析。对于无关请求，可右键选择 “Clear” 清除，或多选后批量删除。如果遇到缓存导致 HTML 或 JSON 未正常展示，也可以右键选择 “No Caching”，让 Charles 在后续请求中忽略缓存，从而抓到完整的响应内容。

筛选完成后，选中你要导出的会话（可以选择整个域名节点，或者按住 Cmd/Ctrl 键多选具体的请求），然后在菜单栏选择 File → Export Session。在导出对话框中，选择 “HTTP Archive (.har)” 格式导出 HAR 文件。

导入 Apifox 自动生成接口文档

打开 Apifox 客户端，进入“项目设置 → 导入数据 → .har 文件”，选择导出的 HAR 文件。

Apifox 会自动解析文件内容，在预览区域显示检测到的接口信息，包括接口数量、请求方法等。导入过程中可以配置选项，例如导入到哪个模块或是否覆盖已有接口。

导入完成后，就可以在对应模块的接口列表里查看了。

完善和优化接口文档

为了稳妥一些，自动生成的接口文档通常需要进一步调整，比如完善接口名称、补充一些参数及其描述、完善响应数据结构，确保文档符合业务需求。

如果接口需要授权，也请在 Apifox 的环境变量或 Auth 设置中配置相应信息。

通过抓包工具录制 HTTP/HTTPS 流量，再导入 Apifox，可以快速生成接口文档并为测试提供真实数据支持。

无论是浏览器、桌面客户端还是移动应用，这种方法都能缩短接口文档的准备时间，让团队快速上手接口测试与开发。

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能和更极致的使用体验！

有任何问题欢迎在 Apifox 用户群与我们交流沟通！

Apifox 11 月更新｜AI 生成测试用例能力持续升级、JSON Body 自动补全、支持为响应组件添加描述和 Header

Apifox — Wed, 26 Nov 2025 02:33:15 GMT

Apifox 新版本上线啦！看看本次版本更新主要涵盖的重点内容，有没有你所关注的功能特性：

「AI 生成测试用例」持续升级
支持先编辑确认用例列表和描述，再生成用例详情
支持生成断言、自定义脚本等前后置操作
支持基于当前的接口测试用例，通过 AI 补充生成更多测试用例
接口调试体验优化
根据接口文档自动补全 JSON Body
获取 OAuth 2.0 Token 后可设为变量的本地值
gRPC 错误响应也支持查看 Metadata & Trailer
支持为响应组件添加描述和 Header
用户反馈优化
全局变量支持多人在线协作、实时自动更新
用 Apifox CLI 指定环境运行测试场景后，收到的 Webhook 通知会包含环境名称

将 Apifox 更新至最新版，一起开启全新体验吧！

「AI 生成测试用例」持续升级

只需在组织层级完成 AI 功能配置，组织内所有团队即可直接使用 AI 生成测试用例。Apifox 将持续迭代优化此功能，以满足更多用户需求与多样化使用场景。

支持先编辑确认用例列表和描述，再生成用例详情

Apifox 本次更新优化了 AI 生成测试用例的流程，引入两步生成机制：

先通过 AI 生成用例列表及描述，用户可预览并进行编辑调整
确认无误后，再生成详细的测试用例内容

通过新增的中间编辑确认环节，使用户能够在生成用例的过程中进行干预和调整，确保生成的测试用例更贴合实际需求，提高测试用例的质量，也让 AI 辅助测试更加灵活可控。

支持生成断言、自定义脚本等前后置操作

更新至最新版 Apifox 后，使用 AI 生成测试用例时，可同时生成断言、自定义脚本等前后置操作，大幅提升测试用例的完整性与可执行性，减少手动配置。

支持基于当前的接口测试用例，通过 AI 补充生成更多测试用例

支持基于接口现有的测试用例，让 AI 补充生成更全面的测试场景。扩展测试覆盖范围的同时，确保新生成的用例与现有测试策略保持一致，从而帮助团队更高效地优化测试方案。

接口调试体验优化

根据接口文档自动补全 JSON Body

若接口文档中已定义 Body 数据结构，调试时将自动提供 JSON 字段补全提示，帮助用户快速准确地填充数据，降低手动输入错误率，提升调试效率。

获取 OAuth 2.0 Token 后可设为变量的本地值

Apifox 支持将获取的 OAuth 2.0 Token 设置为变量本地值，在保护 Token 私密性的同时又能正常用于接口鉴权，避免与团队其他成员共享敏感信息，实现安全高效的协作开发。

gRPC 错误响应也支持查看 Metadata & Trailer

更新至最新版本后，即使 gRPC 接口返回错误，Apifox 仍会正常显示 Metadata 和 Trailer 信息，帮助开发者在异常情况下更快速、精准地定位问题根源，提升 gRPC 调试的完整性和准确性。

支持为响应组件添加描述和 Header

用户现可在 Apifox 中为响应组件添加详细描述，并配置必要的 Header 参数，提升响应组件的完整性和专业性，为团队协作与开发提供更高效、更优质的体验。

用户反馈优化

全局变量支持多人在线协作、实时自动更新

继「环境变量」之后，「全局变量」也已支持多人在线协作与实时同步。团队成员可同时在线编辑全局变量，所有更改都将实时自动同步，确保团队配置始终保持一致，提升协作流畅度与开发效率。

用 Apifox CLI 指定环境运行测试场景后，收到的 Webhook 通知会包含环境名称

当使用 Apifox CLI 指定环境运行测试场景时，Webhook 通知将自动包含环境名称，使测试结果更易追溯与区分，提升多环境测试流程的透明度与可管理性。

了解更多

当然，Apifox 产品团队为大家带来的新功能远不止上方这些：

组织配置好了 AI 功能后，组织内的团队就能直接使用
针对 HTTP Code 进行断言时，支持更多条件
支持模糊搜索模块名称
优化了选择、搜索测试报告中步骤的交互
AI 模型报错时，提供更清晰的提示和指引
AI 生成测试用例时，如果没有选择任何用例类型，会优先基于用户输入指令生成所需用例分类
优化了新建接口时，切换当前接口使用设计界面还是调试界面的交互
运行测试场景时如果选择了私人环境，团队内的其他人会看到“请选择环境”的提示，而不是“环境已被删除”
解决调试 WebSocket 或 Socket.IO 接口时，如果 URL 为 ws:// 且不指定端口，默认连接了 443 端口而不是 80 端口的问题
解决开启了“兼容 HTTP/2”后，如果一个请求还没有得到响应时就发起另一个请求，前一个请求会出现“socket hang up”错误的问题
解决从主分支导出 OpenAPI/Swagger 数据，再导入到子分支，子分支的鉴权组件没有和主分支关联的问题
解决配置 Git 仓库连接时，最多只能显示 30 个 Git 分支的问题

除了新增功能，我们也对产品细节和使用体验进行了优化，具体修改内容可前往 Apifox 更新日志查看。

查看更新日志

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能与更极致的使用体验！

可以前往帮助文档查看更多使用说明和操作，在使用过程中有有任何问题或建议，欢迎在 Apifox 用户群与我们交流沟通。

如何在 Apifox 中使用「模块」合理地组织接口

Apifox — Wed, 12 Nov 2025 02:47:18 GMT

在 Apifox 项目中，接口按照「模块 → 目录 → 接口」的层级结构进行管理。

模块对应独立的 OpenAPI 文件，通常按服务或业务进行划分；目录用于在模块内进行功能分类；接口则是具体的 API 定义。理解这种层级化的设计是合理组织接口的基础，下面是一个简单的层级示例图：

Apifox 项目
│
├── 模块: 用户服务 (按服务或业务划分)
│   │
│   ├── 目录: 用户认证 (功能分类)
│   │   │
│   │   ├── 接口: POST /login (登录)
│   │   └── 接口: POST /register (注册)
│   │
│   └── 目录: 用户信息
│       │
│       └── 接口: GET /users/{id} (获取用户信息)
│
└── 模块: 订单服务
    │
    ├── 目录: 订单管理
    │   │
    │   ├── 接口: POST /orders (创建订单)
    │   └── 接口: GET /orders/{id} (查询订单详情)
    │
    └── 目录: 支付
        │
        └── 接口: POST /payment/submit (提交支付)

理解 Apifox 的「模块」

了解了项目的层级结构之后，我们首先应思考的问题是：是不是每个项目都要用到模块？又该在哪种情况下拆出新的模块？

当你创建一个新项目时，Apifox 会自动为你创建一个“默认模块”。如果你的项目只包含一个后端服务或接口集合，默认模块通常就足够使用。但如果你需要管理多个不同的 API 服务，就可以为每个服务创建独立的模块。

比如某个项目，后端可能包含用户服务、商品服务、订单服务、物流服务等，每个服务负责不同的业务模块，且往往部署在不同的服务地址上。在 Apifox 中，就推荐为这些服务分别创建模块，相对独立地管理各自的接口。

在项目里点击目录树上方的 + 按钮，即可在下拉菜单中看到「模块」的入口。

创建模块后，它会在左侧项目树中与其他模块并列显示，拥有独立的接口和目录空间，可根据需要添加接口和目录。

不同模块之间相对独立，拥有各自的接口、数据模型、组件库和模块变量等，其中“数据模型”可以在模块间互相引用。不同的模块也共享项目级别的配置，如环境变量、数据库连接和公共脚本等。

每个模块对应一份完整的 OpenAPI 规范文件，在导出 OpenAPI Spec 数据时，就可以看到是按“模块”分别导出的。

理解模块内的「目录」

确定模块划分后，下一步就是规划模块内部的结构：接口如何分类、如何设计目录层级，才能让接口更易管理？

每个模块下都有一个默认的根目录，所有接口和子目录都归属于该根目录。

创建新目录时，可以在根目录上新建，也可以在任意现有目录下创建子目录。

目录层级的设计应结合该模块的复杂程度来考虑。如果模块仅包含十几个接口，一层目录通常就足够，直接按功能分类即可；但如果模块较为复杂，一般就需要设计更清晰的多级目录结构。

以“用户服务”模块为例，可以按功能创建用户认证、用户信息、权限管理等一级目录，然后在用户认证目录下直接添加登录、注册、密码重置等接口。

当发现某个目录下的接口数量过多、逻辑上应独立管理时，可以将该目录转换为模块。点击目录右侧的...，在菜单中选择「转换为新模块」即可。这个功能有助于在业务扩展或接口增多时，对项目结构进行更合理的重构。

环境管理与模块的关系

除了接口的结构化组织，不同模块通常对应不同的服务地址和部署环境，这就需要通过环境管理来统一配置，让接口在不同环境下能顺利调用。

在环境设置中，每个模块的“前置 URL”可单独配置。例如在测试环境中，用户服务模块的前置 URL 可以设置为 http://user-service:8001，订单服务模块则为 http://order-service:8002。

按模块来组织接口的项目，在切换环境时，各模块的服务地址都会随之更新。例如，从开发环境切换到测试环境时，用户服务模块的地址会从 http://localhost:8001 切换到 http://user-service:8001，订单服务模块的地址则会从 http://localhost:8002 切换到 http://order-service:8002。

环境变量可在所有模块中共享，适合存放不同环境的配置项；而模块变量则适用于每个模块独有的配置，如各自的 API Key 或 Token，可在对应模块的接口中引用。

数据模型的管理与复用

除了接口和环境的管理，合理规划数据模型同样重要。通过复用数据模型，可以避免重复定义接口参数和响应结构，让接口在模块之间的组织更清晰。

每个模块都有独立的数据模型管理功能，你可以在模块内创建和维护与业务相关的数据结构。这些数据模型不仅能在当前模块中使用，还可以被其他模块引用，从而实现跨模块的数据复用。

例如，用户相关的数据模型可以定义在「用户服务」模块中，订单相关的模型则定义在「订单服务」模块中。当订单模块需要引用用户信息时，只需直接选择「用户服务」模块中的用户数据模型即可，无需重复创建。

拓展：从 Postman 导入的接口怎么组织？

如果团队之前使用 Postman 管理接口，也可以将已有接口直接迁移到 Apifox。

在导入时，每个 Postman Collection 会对应一个模块，文件夹结构会映射为目录。接口和数据模型的组织关系在 Apifox 中能够完整保留，这样既可以沿用原有的接口层级和分类，同时也可以继续在 Apifox 中按照模块、目录和数据模型管理接口。

通过合理的模块划分、清晰的目录组织、规范的数据模型设计，项目的接口结构会更加清晰，也更便于协作和维护。理解 Apifox 的设计理念，并按照这种层级化的方式组织项目，才能让后续的接口管理更高效、更有条理。

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能和更极致的使用体验！

有任何问题欢迎在 Apifox 用户群与我们交流沟通！

如何在 Apifox 中使用 OpenAPI 的 discriminator？

Apifox — Wed, 05 Nov 2025 02:33:01 GMT

我们在往期文章《API 文档中有多种参数结构怎么办？》里讲到过，如果 API 文档中需要用到多种参数结构，那么可以在 Apifox 中使用oneOf、anyOf或allOf 来处理。

在使用这些“组合模式”定义了多种参数结构后，如果参数中有用于标识类型的字段，并且你希望让文档更直观一些，那么可以选择使用 OpenAPI 规范里的discriminator 来进一步区分结构。

什么是 discriminator

在 OpenAPI 中，discriminator 的作用是实现面向对象编程中的“多态性”。

简单来说，它通过一个共享的属性及其唯一的值，来明确指出在 oneOf 或 anyOf 列表中到底应该使用哪一个具体的 Schema。

比如在宠物商店中，我们需要用一个数据模型来描述宠物，但是猫、狗有不同的属性。

狗的数据结构：

{
  "name": "旺财",
  "age": 3,
  "weight": 25.5,
  "petType": "dog",
  "breed": "金毛",
  "isVaccinated": true,
  "walkingSchedule": "早与晚",
  "favoriteToys": ["飞盘","网球"],
  "trainingLevel": "中级"
}

猫的数据结构：

{
  "name": "喵",
  "age": 2,
  "weight": 4.2,
  "petType": "cat",
  "isVaccinated": true,
  "isIndoor": true,
  "litterBoxType": "封闭式",
  "scratchingPostHeight": 120,
  "favoriteSleepingSpot": "阳台"
}

可以看出，虽然都有 petType、name、age 等共同字段，但狗有特有的 breed、walkingSchedule 等字段，猫有特有的 isIndoor、litterBoxType 等字段。

如果在设计 API 文档时仅通过oneOf来定义多个结构，文档上虽然能区分出 Dog 和 Cat 两个 Schema，但每种类型的对应关系并不够直观，读者需要在两个 Schema 标签页之间来回切换对比，参数多的话读起来容易困惑。

而通过设置 discriminator，在文档展示时，它会直接提供一个下拉菜单，让读者可以选择 petType 的值（dog 或 cat），页面会自动展示对应的数据结构。这样就不需要反复比对，也更容易理解整个数据模型的关系，如下图所示：

discriminator 通常与 oneOf 或 anyOf 配合使用。oneOf 定义了对象可能的几种结构，而 discriminator 则告诉解析器如何根据数据内容快速确定应该选用哪一个 Schema。

这样可以让复杂对象的定义更清晰，也能帮助工具在渲染文档或生成代码时自动区分类型。

discriminator 的配置属性

discriminator 包含两个关键属性：

propertyName：指定用于区分类型的字段名称，例如上例中的 petType
mapping：定义字段值与具体 Schema 的映射关系，比如 "dog" 对应狗的 Schema，"cat" 对应猫的 Schema

在 OpenAPI 中的配置示例如下：

discriminator:
  propertyName: petType
  mapping:
    dog: '#/components/schemas/Dog'
    cat: '#/components/schemas/Cat'

在 Apifox 中配置 discriminator

在 Apifox 中设置 discriminator 有两种方式：界面配置结合 JSON Schema，或直接导入 OpenAPI 文件。

界面配置结合 JSON Schema

首先在 Apifox 中创建好对应的数据模型，例如创建 Dog 和 Cat 两个数据模型：

打开需要使用这些数据模型的接口，进入请求体或响应体编辑页面。选择要定义为“组合模式”的字段，点击“高级设置 -> 组合模式 -> oneOf"。

在 oneOf 中引用你需要组合的数据模型，例如 Dog 和 Cat 。

现在已经通过 oneOf 定义了多种可能的结构，接下来需要添加 discriminator 来指定如何区分这些结构。点击 JSON Schema 切换到代码模式：

在适当的位置添加 discriminator 配置（与 oneOf 同级），例如：

"discriminator": {
    "propertyName": "petType",
    "mapping": {
        "dog": "#/definitions/190704823",
        "cat": "#/definitions/190704706"
    }
}

mapping 中的值，如 #/definitions/190704823，是 Apifox 内部为数据模型生成的唯一 ID，你可以在 JSON Schema 配置面板中，找到每个数据模型对应的这个 definitions 路径。

配置完成后保存，在 API 文档里，就可以根据 petType 字段的值智能切换对象类型了。

通过导入 OpenAPI 文件

这是更标准的方式，尤其适合习惯“规范先行”的团队。

你只需直接编写包含 discriminator 的标准 OpenAPI 文件，然后导入到 Apifox 中。

在 OpenAPI 文件中，discriminator 的定义如下：

Pet:
  oneOf:
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Cat'
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      cat: '#/components/schemas/Cat'

这个定义明确了：

通过 oneOf 指定对象可能是 Dog 或 Cat 类型
通过 discriminator 指定根据 petType 字段的值来确定具体类型
通过 mapping 明确 "dog" 对应 Dog Schema，"cat" 对应 Cat Schema。

完整的 OpenAPI 定义如下：

openapi: 3.0.3
info:
  title: Pet Shop API
  version: 1.0.0

components:
  schemas:
    Dog:
      type: object
      properties:
        petType:
          type: string
          enum: [dog]
        name:
          type: string
        age:
          type: integer
        weight:
          type: number
        breed:
          type: string
        isVaccinated:
          type: boolean
        walkingSchedule:
          type: string
        favoriteToys:
          type: array
          items:
            type: string
        trainingLevel:
          type: string
      required:
        - petType
        - name
        - age

    Cat:
      type: object
      properties:
        petType:
          type: string
          enum: [cat]
        name:
          type: string
        age:
          type: integer
        weight:
          type: number
        isVaccinated:
          type: boolean
        isIndoor:
          type: boolean
        litterBoxType:
          type: string
        scratchingPostHeight:
          type: integer
        favoriteSleepingSpot:
          type: string
      required:
        - petType
        - name
        - age

    Pet:
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Cat'
      discriminator:
        propertyName: petType
        mapping:
          dog: '#/components/schemas/Dog'
          cat: '#/components/schemas/Cat'

paths:
  /pets:
    get:
      summary: Get pet information
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'

编写或生成完整的 OpenAPI 文件后，在 Apifox 中选择导入功能。Apifox 会解析文件中的所有定义，自动创建对应的数据模型和接口，同时正确识别 discriminator 配置（这里加上了枚举来锁定参数值）。

常见问题

Q：什么时候用 discriminator

discriminator 的使用前提是你的接口数据中已经有一个用来标识类型的字段。上面例子中的 petType 字段是接口设计时就存在的，用来区分不同类型的宠物。

discriminator 只是告诉 API 文档工具，可以根据这个 petType 字段的值来判断数据结构。

如果你的接口数据中没有这样的区分字段，那就不适合用 discriminator，直接用 oneOf 就够了。

如果结构简单、类型不多，也不一定非要用 discriminator。

Q：discriminator 一定要配 oneOf 吗

是的，必须和 oneOf、anyOf 或 allOf 结合使用。它本身不能单独定义数据结构，只是用来指定如何在多种可能的结构中进行区分。

discriminator 是 OpenAPI 规范中的一个可选功能，用来增强 oneOf/anyOf/allOf 的使用体验。
当你的接口数据中已经包含用于标识类型的字段时，可以通过在 Apifox 中配置 discriminator，来让 API 文档更清晰、更智能。
当然，如果你觉得配置麻烦，或者数据结构相对简单，完全可以只使用 oneOf 等组合模式。

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能和更极致的使用体验！

有任何问题欢迎在 Apifox 用户群与我们交流沟通

Apifox 10 月更新｜支持实时预览在线文档个性化配置的效果、性能优化、测试能力升级

Apifox — Wed, 29 Oct 2025 02:39:51 GMT

Apifox 新版本上线啦！

看看本次版本更新主要涵盖的重点内容，有没有你所关注的功能特性：

在线文档个性化设置，可实时预览效果
新增「性能优化」功能
优化项目内标签页的渲染
GPU 硬件加速开关
测试能力升级
测试用例增加「标签」
支持针对 HTTP Code 进行断言
「测试场景」支持批量修改
支持配置分支管理员能否直接修改被保护的分支内容
使用网页版的云端 Agent 调试 AI 大模型接口时，可正常展示时间线内容
用户反馈优化
支持将 null 提取为变量的值
新增必选权限后，所有自定义角色会自动拥有该权限

将 Apifox 更新至最新版，一起开启全新体验吧！

在线文档个性化设置，可实时预览效果

Apifox 优化了在线文档的个性化配置体验，新增实时预览功能。在左侧调整设置项的同时，可以在右侧预览窗口立即看到效果变化，使配置过程更直观清晰，帮助快速找到文档的最佳展示方式。

新增「性能优化」功能

优化项目内标签页的渲染

「性能优化」中新增了「优化项目内标签页渲染」选项，开启后能有效解决打开大量 Tab 时出现的卡顿问题，提升多标签场景下的性能表现，带来更顺畅的操作体验。

GPU 硬件加速

「性能优化」中新增了「GPU 硬件加速」选项。当遇到界面闪烁或渲染不完整等显示问题时，可尝试关闭该选项，提升使用体验。

测试能力提升

测试用例增加「标签」

测试用例新增了「标签」功能，支持对标签和分类进行管理，帮助团队更精准地分类、检索及管理测试用例，提升测试用例的管理效率与规范性。

支持针对 HTTP Code 进行断言

本次更新，Apifox 扩展了断言功能的覆盖范围，支持针对 HTTP Code 进行断言验证，可以更好地确保接口行为符合预期，提升接口测试的准确性与便捷性。

「测试场景」支持批量修改

Apifox 新增「测试场景」批量修改功能，支持同时对多个场景进行优先级调整、标签管理、移动或删除等操作，大幅减少重复工作时间，提升测试场景管理效率，使测试场景的维护工作更加高效便捷。

支持配置分支管理员能否直接修改被保护的分支内容

Apifox 新增了更精细的分支权限控制功能，支持在设置分支管理员时，定义其是否拥有直接修改受保护分支内容的权限，从而在保障分支安全性的同时，精确控制分支管理员的操作权限，兼顾安全性与操作灵活性。

使用网页版的云端 Agent 调试 AI 大模型接口时，可正常展示时间线内容

在使用 Apifox 网页版的云端 Agent 调试 SSE 流式响应的 AI 大模型接口时，可实时展示时间线内容，并预览 Markdown 格式的响应结果，大幅提升调试 AI 接口的便捷性和可读性。目前该功能已在 Apifox 客户端和网页版中全面支持。

用户反馈优化

支持将 null 提取为变量的值

Apifox 现在支持将 null 值提取为变量，使得变量提取更加完整和灵活，能够处理包含 null 值的各种场景，更准确地捕获和使用接口返回的所有数据类型，提升测试场景的覆盖度和准确性。

新增必选权限后，所有自定义角色会自动拥有该权限

更新至最新版的 Apifox 后，新增必选权限时，所有自定义角色将自动获得该权限，无需额外手动配置。确保所有角色都能及时获得必要的基础权限，简化了权限管理流程，保证了系统功能的正常使用。

了解更多

当然，Apifox 产品团队为大家带来的新功能远不止上方这些：

设计接口时选择 204 状态码，内容格式会自动切换为 No-Content
优化了 AI 修改数据模型、AI 模型功能商配置的界面
项目外成员点击在线文档的 “Run in Apifox” 调试接口时，可以编辑环境变量的本地值
项目内导入数据的界面，新增“通过 API 导入”功能的入口
编辑接口时，点击字段引用的模型，会展示当前模块的模型列表
优化了调试接口时响应区域的样式
请求异常时，针对不同情况提供更清晰的提示
测试报告的结果分类中，展示每一类中的具体数量
在 macOS Tahoe 26 系统不显示软件边框和阴影，以解决 GPU 占用过高所导致的卡顿问题
解决导入 YApi 数据时，只导入了一个目录的问题
解决提取响应示例并选择覆盖已有示例时，没有自动填充示例名称的问题
解决在 OAuth 2.0 的 Auth URL 使用了变量时，变量优先级不正确，导致环境变量的值没有生效的问题
解决接口引用了 allOf 组合模式的数据模型后，生成模型代码时，类名不是模型名称而是数字的问题
解决模块概览页导出/备份 OpenAPI 数据的永久链接，没有正常显示引用了鉴权组件的接口的 security 字段的问题

除了新增功能，我们也对产品细节和使用体验进行了优化，具体修改内容可前往 Apifox 更新日志查看。

查看更新日志

欢迎各位用户对 Apifox 继续提出使用反馈和优化意见，我们会持续优化更新，致力于为用户提供更优秀的产品功能与更极致的使用体验！

可以前往帮助文档查看更多使用说明和操作，在使用过程中有有任何问题或建议，欢迎在 Apifox 用户群与我们交流沟通。