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

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

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

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

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

Swagger-1
那么使用 Swagger 就可以万事大吉了吗?

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

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

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

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

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

Swagger-2

那么,既然 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,分享半个互联网人的技术与思考,感兴趣的可以关注.
404Code

©️2020 CSDN 皮肤主题: 编程工作室 设计师: CSDN官方博客 返回首页
实付0元
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值