Swagger API 接口文档生成工具的利与弊
作为Java后台工程师其中的一员，作者深知众多的开发者没有写接口文档的习惯。尤其是一些新手，他们只想着把功能实现、和前端开发者把接口调试通就好了，没有考虑到后期的项目维护。当他们接受一个旧项目，进行二次开发的时候，突然发现看别人的代码太难了，既没有注释，也没有接口文档，看懂一块代码逻辑要大半天，时间都浪费在了读懂旧代码上了。
为了能够偷懒(不写接口文档)，开发者发明了一种神器—Swagger，这个工具能够自动生成API接口文档，在线调试，非常的方便。
Swagger官方文档:https://swagger.io/
SpringBoot2.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.1Header参数参数名必选类型/参数值说明Content-Type是application/json请求参数类型5.2Body参数参数名必选类型限制条件说明account是string1