很多做接口开发的朋友，大概率都用过Swagger写接口文档，后来接触到Apifox，觉得它功能更全，能管接口还能做测试和mock，就想着把文档迁过去，但一导入就傻眼：怎么字段名变了？之前加的备注分组没了？必填的字段变成选填？这些坑我们迁移的时候全踩过，今天就把遇到的问题、修复方法还有踩坑的心得全讲清楚。
一、迁移前的准备：先摸透两个工具的差异
1.1 两个工具对字段的“认知”不一样
Swagger是纯接口文档工具，对自定义的字段和命名规则比较宽松，而Apifox是集成化的接口平台，为了统一管理，会默认做一些自动处理，这就是兼容问题的根源。比如Swagger里的小驼峰字段，Apifox可能自动改成下划线，或者反过来；Swagger自己加的自定义备注字段，Apifox不认就直接丢了；还有必填字段的标记，两个工具的规则也有点不一样。
1.2 提前扫一遍Swagger的文档
迁移前先把Swagger导出的JSON文件拉出来，用文本编辑器搜一搜，看看有没有x开头的自定义字段（比如我们用来标分组的x-module），有没有下划线或者小驼峰的特殊字段，提前记下来，这些都是可能踩坑的点，别等导入后才发现。
二、遇到的不兼容字段具体案例及修复
2.1 字段命名自动转换：导致接口传参报错
这是我们遇到最多的问题，比如Swagger里写的是小驼峰的userName，导入Apifox后自动变成username，要是后端实际要的是userName，前端传参就会报错。 举个例子，下面是我们项目里的Swagger片段，技术栈用JSON：
{
"swagger": "2.0",
"paths": {
"/user/add": {
"post": {
"parameters": [
{
"name": "userName",
"in": "body",
"required": true,
"type": "string",
"description": "用户的登录名"
},
{
"name": "userAge",
"in": "body",
"required": true,
"type": "integer",
"description": "用户的年龄"
}
]
}
}
}
}
导入Apifox后，字段名全变成了username和userage，连大小写都改了，测试的时候调用接口，后台提示找不到username，应该找的是userName，这时候怎么修？ 很简单，在Apifox里重新导入的时候，找到“导入设置”，里面有个“自动转换命名风格”的选项，把勾去掉就行，重新导入后，字段就保留原来的userName了。要是已经导入了，也可以批量选所有字段，手动改名字，Apifox支持批量编辑字段名，不用一个个改。
2.2 自定义扩展字段丢失：分组和备注没了
Swagger里我们有时候会加一些自己用的字段，比如用来标接口属于哪个模块的x-module，导入Apifox后，这些字段直接消失，导致接口没分到对应的模块，找起来麻烦。 比如下面的Swagger片段，加了x-module字段标属于用户模块：
{
"swagger": "2.0",
"info": {
"title": "用户管理接口",
"version": "1.0"
},
"x-module": "用户模块",
"paths": {
"/user/list": {
"get": {
"description": "获取用户列表"
}
}
}
}
导入Apifox后，x-module这个字段不被识别，所以这个接口没分到用户模块，这时候有两个修复方法： 一是手动在Apifox里新建“用户模块”的分组，把这个接口拖进去，适合少量接口；二是把Swagger里的自定义字段改成Apifox认识的，比如把x-module改成x-apifox-module，这样重新导入后，Apifox就能自动把接口放到对应的分组里，适合批量接口。
2.3 必填字段标记不一致：mock数据没生成
Swagger里用required数组标记必填字段，比如required: ["userName", "userAge"]，但导入Apifox后，这些字段默认变成可选，导致生成的mock数据里没有这些必填字段，测试接口的时候会报错。 修复方法也简单，要是只有几个字段，就手动把每个字段的“必填”勾打上；要是有很多字段，Apifox的批量编辑功能可以一键勾选所有字段的必填，操作方法是：选中要处理的所有字段，点“批量编辑”，找到“必填”选项，打勾保存就行，这样mock数据就会自动生成这两个必填字段了。
三、迁移后的迁移心得与注意事项
3.1 迁移前的预检查很重要
我们第一次迁移就是没做预检查，直接导入，结果花了3天改字段，后来总结出预检查的步骤：先导出Swagger的JSON，用文本编辑器搜x开头的自定义字段、下划线和小驼峰的特殊字段，提前记下来，迁移的时候重点处理这些，能省很多时间。
3.2 迁移中用批量功能提高效率
Apifox的批量编辑功能是真的香，不管是改字段名、改必填、改类型，都能批量操作，不用一个个改。比如我们导入了100个接口，有20个字段被自动转成了下划线，用批量选这些字段，统一改回小驼峰，几分钟就搞定了，要是一个个改，估计要花一两个小时。
3.3 迁移后一定要做验证
导入完不是就完事了，一定要验证几个点：一是接口的字段名对不对，二是必填字段有没有打勾，三是分组有没有正确，四是mock数据能不能正常生成。我们当时验证的时候，发现有5个接口的分组没识别对，手动拖一下就好了，没影响后续的测试。
四、应用场景与技术优缺点
4.1 常见应用场景
我们迁移的场景是：团队从纯后端开发，转成前后端协作，原来用Swagger开源版，每个人改的接口都要自己存，经常有冲突，后来选Apifox是因为它有团队协作功能，多人同时编辑，还有测试用例的功能，适合需要团队一起维护接口文档的项目；个人开发者要是觉得Swagger UI太简单，想找个能做mock和接口测试的工具，也适合用Apifox，迁移Swagger文档过去就能用。
4.2 两个工具的优缺点对比
Swagger的优点是开源免费，不用额外下载工具，直接用浏览器打开Swagger UI就能写文档，支持所有常见的编程语言，生态很好；缺点是功能太单一，没有mock的高级功能（比如不能返回随机的手机号、身份证），团队协作麻烦，容易有文档冲突。 Apifox的优点是集成了接口文档、mock、测试用例、团队协作四个功能，不用再用多个工具，权限管理很细，能控制谁能改文档；缺点是部分老Swagger的自定义字段不兼容，需要手动处理，而且免费版的功能有限，要是团队人多，可能需要买付费版。
五、文章总结
从Swagger迁移到Apifox，核心是要先摸透两个工具的差异，别上来就直接导入，预检查能帮你避开大部分坑；遇到不兼容的字段，分清楚是命名转换、自定义字段丢失还是必填标记的问题，然后用对应的方法修复，批量功能能帮你省很多时间；迁移后一定要做验证，确保所有字段都正确，这样迁移后的收益才会最大，比如团队协作更顺畅，接口测试更高效。
Comments