来个老套的开场白O(∩_∩)O 、、、是不是厌烦了编写大量的前后端对接的文档？是不是厌烦了各版本的新旧文档的混淆？是不是疲于跟前端对接人员无意义的重复沟通？ 妈妈不担心系列又来了~
以我们目前项目为例，springboot开发、RESTful API 设计、前后端分离。为解决以上的痛点，我在项目中推行了一个重磅的好伙伴Swagger-ui 我称它为可视化实时在线文档。
额，我贴一个官方汉化版demo例子给各位看官瞅瞅
是不是狠fashion？ 哈哈
springboot集成Swagger2的教程很多 我就不献丑了，推荐一个上手容易的
了解后，肯定有看官会问”这样是不是对代码的侵入性太强了？”
是的，没错。就目前而言鱼与熊掌不可兼得，如果有更好的方法求推荐！！。
下面主要记录下我使用过程中一些心得，算是抛砖引玉了。（后期还会继续更新）
先说下注意点： 使用的是jackson，网上看一些技术大牛反映 swagger与fastjson的兼容性不太好。
@ApiOperation/@ApiImplicitParam
我们可以通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明
其中@ApiOperation和@ApiImplicitParam为添加的API相关注解，参数说明如下：
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”) 其他参数可参考源码；
一个完整的例子如下（不太复杂的话，这些基本上都能搞定，参数值所代表的位置我用红框标注了）
ps：对于paramType 我看了下源码 有五个可选值
@GetMapping是Spring4.3新特性，等同于
@RequestMapping(method = RequestMethod.GET)，相似的还有@PostMapping 可以自行研究。
我实践后的心得
- path 用法： /get/{userCode}
- query 用法： /get?userCode=1
- body 用法： post方式提交
- header 用法： (应该用的不多)
- form 用法： 表单方式提交
@ApiIgnore
如果你的接口方法不想暴露在Swagger-ui给前端查看可以使用@ApiIgnore注解来隐藏
@Api
一般用在Controller类级别上增加接口说明。
@ApiModel/@ApiModelProperty
@ApiModel用于前端请求实体层类的说明
@ApiModelProperty用于前端请求实体层字段属性上增加对该字段的说明。
好啦，完工~
一些想法：
对于把多个工程里的swagger引导到一个页面里，我目前想到的解决办法是做个index界面引导下
建议swagger 的版本得用2.6.1以上，或者2.5.0以下 否则会踩坑。
- 本文标题： springboot集成swagger-ui
- 文章作者： sherryriver（木木三可）
- 发布时间： 2016.11.07
- 本文链接： https://sherryriver.github.io/2016/11/07/swagger/
- 许可协议： "署名-非商用-相同方式共享 4.0" 转载请保留原文链接及作者。