本文介绍了如何在项目开发中有效地利用Swagger来编写接口文档，提升开发效率。建议在已有后台框架时直接编写服务端代码并用Springfox-Swagger生成描述文件；在前期缺乏框架时，先编写Swagger描述文件以快速提供接口文档。在项目迭代阶段，更新接口只需修改代码并生成新文档，便于前端使用。此外，提供接口模拟数据能极大地帮助前端开发，通过Swagger注解可以生成详细的请求和响应示例。
一般来说，接口文档都是由服务端来编写的。在项目开发阶段的时候，服务端开发可以视情况来决定是直接编写服务端调用层代码，还是写Swagger描述文件。
建议是如果项目启动阶段，就已经搭好了后台框架，那可以直接编写服务端被调用层的代码（即controller及其入参出参对象），然后通过Springfox－swagger 生成swagger json描述文件。
如果项目启动阶段并没有相关后台框架，而前端对接口文档追得紧，那就建议先编写swagger描述文件，通过该描述文件生成接口文档。后续后台框架搭好了，也可以生成相关的服务端代码。
项目迭代阶段
到这个阶段，事情就简单很多了。后续后台人员，无需关注Swagger描述文件和接口文档，有需求变更导致接口变化，直接写代码就好了。把调用层的代码做个修改，然后生成新的描述文件和接口文档后，给到前端即可。真正做到了一劳永逸。
推荐流程
上面的流程就是在开发阶段，和我们的调用代码一起编写，一个调用接口编写时，根据此接口的功能因为，入参和出参就可以定下来，这个时候我们就可以编写swagger文档，然后在编写我们的实际代码。
有的时候我们需要把文档静态化，导出html或pdf，就可以利用maven插件去实现
给Mock系统的正常请求及响应全流程数据
很多时候，如果你能在提供接口文档的同时，把所有接口的模拟请求响应数据也提供给前端。或者有Mock系统，直接将这些模拟数据录入到Mock系统中，那将会提高前端的开发效率，减少许多发生在联调时候才会发生的问题。
通过适当地在代码中加入swagger的注解，可以让你的接口文档描述信息更加详细，如果你把每个出入参数的示例值都配上，那前端就可以直接在接口文档中拿到模拟数据。
如下： 
通过example属性，可以模拟请求数据报文，如下
上图是请求参数的案例。
上图是返回值的案例，非常清晰，还有相关的案例数据。
总结
1526)]
上图是返回值的案例，非常清晰，还有相关的案例数据。
扫一扫
384
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
