Apifox 接口文档「额外字段 HashMap」的校验设置，快速上手!

最新推荐文章于 2024-06-13 08:37:22 发布

Apifox.

最新推荐文章于 2024-06-13 08:37:22 发布

阅读量607

点赞数 25

文章标签： java html 学习方法改行学it 后端

本文链接：https://blog.csdn.net/m0_71808387/article/details/137262271

版权

「额外字段」指的是那些未在接口文档中明确定义的字段。出现「额外字段」的场景可能是因为业务进行了升级，导致接口返回的数据在原来的基础上增加了一些新的字段，但是接口文档中定义的数据结构尚未做相应的更新，这就出现了接口返回数据与文档定义之间的不匹配问题。

针对这种情况，Apifox 最新版本提供了一项功能，允许用户自定义设置对「额外字段」的校验响应。这意味着你可以选择在遇到「额外字段」时是否接收提示，从而更灵活地处理接口返回数据与文档定义不一致的问题。

举个例子，假设接口文档中定义的数据结构如下所示，这里面并未包含 email 字段：

{
    "code": "0",
    "message": "ok",
    "data": {
        "id": "1001",
        "name": "张三",
        "age": 33
    }
}

在实际发送请求后，响应数据中却出现了额外未定义的 email 字段，但是这个时候你会发现，校验响应的控制台里并没有产生预期的错误提示，这是因为 Apifox 在默认设置中允许响应数据包含「额外字段」，并不会对这些未预定义的字段进行校验。

但在某些情况下，我们可能对开发有着更为严格的要求。像上面的例子那样，如果接口响应中新增了「额外字段」，我们可能希望在校验响应的控制台中接收到错误提示，以确保数据结构的完整性和一致性。这时，要怎么实现呢？

触发对「额外字段」的校验非常简单！有两种方法：

注意，要使用此功能，你需要将 Apifox 的版本升级到 2.5.15 以上。

你可以在「项目设置 - 功能设置 - 响应校验设置」里，对“Object 对象允许额外字段”的选项进行开启或关闭，该全局设置将对项目内所有接口生效。

具体来说，该功能默认处于启用状态，它确保即便响应数据中出现了文档未定义的字段，也不会触发校验错误提示。

相反，关闭此选项意味着返回的接口数据必须与 接口文档 的定义严格一致，任何额外的未定义字段都将引起校验错误，控制台里会提示“不允许有额外的属性” 。

除了全局设置之外，你还可以针对单个接口进行细化设置。通过访问「修改文档」下的「返回响应」部分，进而选择 object 对象的「高级设置」来实现。在弹出的配置界面中，你将能够对额外字段（HashMap）进行特定配置。

这里设置的「额外字段」其实是 HashMap 的概念，什么是 HashMap？简单讲就是一组键值对的集合，也可以称为 Map、字典或关联数组，各种编程语言中可能采用不同的术语，但基本概念相同。

在接口中配置额外字段共有三个选项，分别是「未配置」、「允许」和「禁止」。默认选择「未配置」。如果选择「允许」，那么你还可以进一步设置字段值的类型，并根据不同的字段值类型设置属性。

在 OpenAPI 规范中，你可以定义一个键为字符串类型的 HashMap，并且你还可以明确规定这些字符串键所对应的值的数据类型，这样做可以让你灵活定义接口期望接收的「额外字段」。

举个例子，假设我们需要设计一个字段，该字段可以包含任意数量的键值对，其中每个键值对的值都为字符串类型。在 Apifox 中，我们可以将额外字段值的类型设置为 string 来实现。

保存后，你可以在接口文档内的返回响应示例中看到符合定义的数据结构和示例值。

💡 更专业的解释

在 OpenAPI 规范中，你可以定义一个键为字符串类型的 HashMap，这是通过将一个对象（object）的元素类型标记为 additionalProperties ，并指定键值对中值的类型来实现的。

additionalProperties 是 OpenAPI 规范中的一个关键字，它用于描述对象中那些没有明确声明的属性，这个关键字用于指定对象中的“额外属性”，即除了在对象定义中已经明确说明的属性之外的所有属性。

在标记了 additionalProperties 的情况下，我们需要进一步定义这些“额外属性”的值应当是什么类型。值的类型可以是任何有效的数据类型，如字符串（string）、数字（number）、布尔值（boolean）或其他对象（object）等。

需要注意的是，「接口级别的设置」拥有比「全局设置」更高的优先级，也就是说，你在接口中设置的操作都会默认覆盖全局的。

除此之外，最新版的 Apifox 还支持其它响应校验的设置，还是在「项目设置 -> 功能设置 ->响应校验设置」中选择。

你可以把“自动化测试”的校验响应选项给关了，这样在调试时，“自动化测试”的“测试步骤”详情页里就不会再显示“校验响应”功能。

你也可以选择只校验响应 HTTP 状态码，或者只校验响应 Body 的数据结构，关键取决于你的业务需求。

新版的 Apifox 提供了灵活的数据校验选项，你可以通过全局或接口级设置来控制是否允许响应数据包含未定义的额外字段。

关注