Swagger2构建RESTful APIs详解

公告：“业余草”微信公众号提供免费CSDN下载服务(只下Java资源)，关注业余草微信公众号，添加作者微信：xttblog2，发送下载链接帮助你免费下载！
本博客日IP超过2000，PV 3000 左右，急需赞助商。
极客时间所有课程通过我的二维码购买后返现24元微信红包，请加博主新的微信号：xttblog2，之前的微信号好友位已满，备注：返现
受密码保护的文章请关注“业余草”公众号，回复关键字“0”获得密码
所有面试题(java、前端、数据库、springboot等)一网打尽，请关注文末小程序

腾讯云】1核2G5M轻量应用服务器50元首年，高性价比，助您轻松上云

自从 restfull 概念被提出，各种框架 rest 框架如雨后春笋般的冒了出来。网上也有很多网友总结了spring boot + swagger2 的整合用例。但是很多例子是运行不成功的，而且还被转载来转载去的。
本文将从 swagger2 的注解上来详细讲解如何使用它。

swagger用于定义API文档

swagger2好处

• 前后端分离开发
• API文档非常明确
• 测试的时候不需要再使用URL输入浏览器的方式来访问Controller
• 传统的输入URL的测试方式对于post请求的传参比较麻烦（当然，可以使用postman这样的浏览器插件）
• spring-boot与swagger的集成简单的一逼

swagger2 注解说明

• @Api：用在类上，说明该类的作用
• @ApiOperation：用在方法上，说明方法的作用
• @ApiImplicitParams：用在方法上包含一组参数说明
• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  • paramType：参数放在哪个地方
    • header–>请求参数的获取：@RequestHeader
    • query–>请求参数的获取：@RequestParam
    • path（用于restful接口）–>请求参数的获取：@PathVariable
    • body（不常用）
    • form（不常用）
  • name：参数名
  • dataType：参数类型
  • required：参数是否必须传
  • value：参数的意思
  • defaultValue：参数的默认值
• @ApiResponses：用于表示一组响应
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  • code：数字，例如400
  • message：信息，例如"请求参数没填好"
  • response：抛出异常的类
• @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
  • @ApiModelProperty：描述一个model的属性

需要注意的是：

如果ApiImplicitParam中的phone的paramType是query的话，是无法注入到rest路径中的，而且如果是path的话，是不需要配置ApiImplicitParam的，即使配置了，其中的value="手机号"也不会在swagger-ui展示出来。

启动服务，浏览器输入"http://localhost:8080/swagger-ui.html"

最后，欢迎关注我的个人微信公众号：业余草（yyucao）！可加作者微信号：xttblog2。备注：“1”，添加博主微信拉你进微信群。备注错误不会同意好友申请。再次感谢您的关注！后续有精彩内容会第一时间发给您！原创文章投稿请发送至532009913@qq.com邮箱。商务合作也可添加作者微信进行联系！

本文原文出处：业余草： » Swagger2构建RESTful APIs详解