Swagger2构建RESTful APIs详解

JAVA herman 4140浏览 0评论
公告:“业余草”微信公众号提供免费CSDN下载服务(只下Java资源),关注业余草微信公众号,添加作者微信:xttblog,发送下载链接帮助你免费下载!
本博客日IP超过1800,PV 2600 左右,急需赞助商。
极客时间所有课程通过我的二维码购买后返现24元微信红包,请加博主新的微信号:xttblog,之前的微信号好友位已满,备注:返现
所有面试题(java、前端、数据库、springboot等)一网打尽,请关注文末小程序
视频教程免费领

自从 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的属性

需要注意的是:

swagger2 整合 spring boot

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

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

swagger2 测试

业余草公众号

最后,欢迎关注我的个人微信公众号:业余草(yyucao)!可加QQ1群:135430763(2000人群已满),QQ2群:454796847(已满),QQ3群:187424846(已满)。QQ群进群密码:xttblog,想加微信群的朋友,之前的微信号好友已满,请加博主新的微信号:xttblog,备注:“xttblog”,添加博主微信拉你进群。备注错误不会同意好友申请。再次感谢您的关注!后续有精彩内容会第一时间发给您!原创文章投稿请发送至532009913@qq.com邮箱。商务合作可添加助理微信进行沟通!

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