Swagger API 接口文档生成工具的利与弊

作为Java后台工程师其中的一员，作者深知众多的开发者没有写接口文档的习惯。尤其是一些新手，他们只想着把功能实现、和前端开发者把接口调试通就好了，没有考虑到后期的项目维护。当他们接受一个旧项目，进行二次开发的时候，突然发现看别人的代码太难了，既没有注释，也没有接口文档，看懂一块代码逻辑要大半天，时间都浪费在了读懂旧代码上了。

为了能够偷懒(不写接口文档)，开发者发明了一种神器— Swagger ，这个工具能够自动生成 API 接口文档，在线调试，非常的方便。

Swagger 官方文档: https://swagger.io/

SpringBoot 2.X集成Swagger2生成 RESTFul 风格API接口文档

那么使用 Swagger 就可以万事大吉了吗？

作者在这里根据自己的使用情况对其做了一些总结，仅供参考。

先说优点吧，毕竟这工具确实提升了不少工作效率。

• 1 节省了大量手写接口文档的时间，这是最大的优势
• 2 生成的接口文档(参考上图)可以直接在线测试，省去了使用 Postman 设置接口参数的过程，而且请求参数，返回参数一目了然
• 3 接口按照模块已经分类好了，很清晰

Swagger 既然这么方便，那么就没有缺点了吗？不，缺点也很明显

• 1 为了能够实现自动生成接口文档，需要在代码中提前写大量的注解，生成的接口文档越清晰，写的注解越多(参考图 2)
• 2 对于复杂功能，一个功能需要多个模块配合的情况下，联调测试将会是一件非常令人头疼的事。举个例子: 后台排课功能，这个涉及到的模块包括教师，学生，课程等等，这是在一个界面实现的，每个模块都是分开的，生成排课表这个功能涉及到以上模块，但是前端开发者不熟悉每个模块之间的联系，找到每个模块对应的接口就需要花费时间，甚至这个功能使用到哪些接口都不清楚，而 Swagger 不支持自定义接口文档，不能指明某一个功能需要使用哪些接口，有什么注意事项
• 3 对于返回结果不能添加说明或者实现这个功能非常麻烦。虽然 Swagger 有 @ApiResponse
  注解用来说明返回结果，但是这个使用并不方便，而且如果返回的并不是对象的时候(如 Map),就无法实现给每一个返回字段的说明。如果将所有的返回结果都是用对象封装，然后添加注解，这又是一个非常大的工作量
• 4 无法测试错误的请求方式、参数等。如接口指定使用 POST 请求，则无法使用 swagger 测试 GET 请求的结果，也无法自定义 Header

那么，既然 Swagger 也有缺点，到底该不该用呢?

这个作者也给不了确定的答案，还需要开发者根据自身的情况来决定。

下边是作者不使用 Swagger 的一个接口文档解决方案,仅供参考:

使用该文档作为一个模板，然后将每一个接口参数放到对应的位置，每一个接口保存一个文件，同一模块的接口文档放在一个文件夹下。

模板源文件GitHub地址: RESTful 风格 API 接口文档模板

---

RESTful 风格 API 接口文档模板

​
​

1 接口名称

用户注册接口

2 接口描述

• 用户信息注册
• 用户可以通过 手机号/邮箱 进行注册
• 同一个 手机号/邮箱只能注册一个账号

3 请求地址

{apiAddress}/api/user/signup

4 请求方式

POST

5 请求参数

5.1 Header 参数

参数名	必选	类型/参数值	说明
Content-Type	是	application/json	请求参数类型

5.2 Body 参数

参数名	必选	类型	限制条件	说明
account	是	string	1 < length < 50	用户账号
passcode	是	string	1 < length < 50	密码
checkCode	是	string	length = 6	验证码

注意事项: 密码(passcode) 的加密方式为 xxxxxx

需要调用到的其他接口:

接口名称	接口地址	用途说明
获取验证码	{apiAddress}/api/common/getCheckCode	获取注册所需验证码

​

6 返回示例

{
    "code": 200,  // 状态码
    "msg": "成功",  // 提示信息
    "data": null  // 返回内容
}

​

7 备注

更多返回错误码请查看首页返回状态码表

接口返回状态码表

---

模板源文件GitHub地址: RESTful 风格 API 接口文档模板

个人公众号:404Code,分享半个互联网人的技术与思考，感兴趣的可以关注.