夜雨聆风写API文档写到怀疑人生，你有过这种体验吗？
我刚带团队那会，后端同事天天抱着电脑敲文档。一个接口要写参数、写返回值、写异常情况，一个项目几十个接口，光文档就能写两天。前端同事更惨，接口一变，文档跟不上，联调时候全靠猜。两边都憋着火。
后来我发现，写文档这个活，其实可以甩给机器干。Swagger就是这个干活的机器。
Swagger不是魔法，它就是个规范。你给代码加上几个注解，它自动生成文档。后端不用手写word，前端不用追着问接口字段。大伙都能省下时间干点正经事。
怎么用？举个例子。你写了个用户登录接口，正常写法是public String login(String username, String password)。想生成文档？加个@ApiOperation(“用户登录”)，再给参数加上@ApiParam(“用户名”)。就这两行代码，Swagger自动给你生成一个漂亮的文档页面。接口的调用方式、参数类型、返回值格式，全在上面。
这玩意最爽的地方在哪儿？接口改了，文档自动跟着改。你后端改了参数名，前端打开页面一看，新的参数名已经更新上去了。不用再跑过来问“哥们你那个字段是不是改了”，也不用在群里艾特全体成员“文档已更新”。
当然，光有工具不行，关键是团队要养成习惯。我见过有人装了Swagger，注解一个也不写，文档页面上全是乱码。这就跟买了洗碗机不用，非得手洗一样，白瞎。
还有个小坑要注意。Swagger生成文档的时候，会把所有的接口都展示出来。有些内部接口不想暴露？可以在注解里加个hidden=true，或者用分组功能，把文档分成对内和对外两个版本。这个设置花不了两分钟，但能省很多解释工作。
前后端怎么配合？后端写好注解后，把项目跑起来，访问/swagger-ui.html这个地址，就看到了文档。前端把这个链接存到浏览器收藏夹里，随时看。联调时候，直接在文档页面点“try it out”按钮，输入参数测试接口，连Postman都不用开。
我带的几个项目，推行Swagger之后，前后端吵架的次数少了七八成。以前每次联调，前端总说“文档里没这个字段”，后端总说“我明明写了”。现在打开文档一对照，谁对谁错清清楚楚。文档变成活的，争议就少了。
有人问，Swagger会不会泄露接口信息？正式上线的时候，把文档关掉就行。或者用生产环境的配置，把Swagger的开关设成false。只有开发环境和测试环境才开。这个操作一行代码，没啥难度。
说白了，写文档不痛苦，痛苦的是改文档。手写一份文档，改了十几版，最后发现和代码对不上了。Swagger解决的就是这个痛点，让文档跟着代码活起来。后端轻松，前端省事，项目进度也快。两边都给你点赞，这事不亏。
