swagger 注解使用

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger的目标是对REST API定义一个标准的和语言无关的接口,可让人和计算机无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过Swagger进行正确定义,用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger消除了调用服务时可能会有的猜测。

关于Swagger的集成请参考:https://github.com/yinjihuan/spring-boot-starter-swagger
##API
@Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式如下:

@Api(value="企业用户控制器", tags={"用户接口"})
@RestController
@RequestMapping("/user")
public class EnterpriseProductUserController {

}

效果图如下:

image.png

  • value:接口说明
  • tags:接口说明,可以在页面中显示。可以配置多个,当配置多个的时候,在页面中会显示多个接口的信息

##ApiModel
@ApiModel用在类上,表示对类进行说明,用于实体类中的参数接收说明,使用方式如下:

@ApiModel(value = "com.fangjia.fsh.user.query.LoginQuery", description = "登录参数")
public class LoginQuery {

}

效果图如下:

image.png

ApiModelProperty

@ApiModelProperty()用于字段,表示对model属性的说明,使用方式如下:

@ApiModel(value = "com.fangjia.fsh.user.query.LoginQuery", description = "登录参数")
public class LoginQuery {

    @ApiModelProperty(value = "企业编号", required = true)
    private Long eid;

    @ApiModelProperty(value = "用户编号", required = true)
    private String uid;

}

效果图如下:

image.png

ApiParam

@ ApiParam用于Controller中方法的参数说明,使用方式如下:

@PostMapping("/login")
public ResponseData login(@ApiParam(value = "登录参数", required = true) @RequestBody LoginQuery query) {

}

效果图如下:

image.png

  • value:参数说明
  • required:是否必填

ApiOperation

@ApiOperation用在Controller里的方法上,说明方法的作用,每一个接口的定义,使用方式如下:

@ApiOperation(value = "用户登录", notes = "企业用户认证接口,参数为必填项")
@PostMapping("/login")
public ResponseData login(@ApiParam(value = "登录参数", required = true) @RequestBody LoginQuery query) {

}

效果图如下:

image.png

  • value:接口名称
  • notes:详细说明

ApiResponse和ApiResponses

@ApiResponse用于方法上,说明接口响应的一些信息,@ApiResponses组装多个@ApiResponse,使用方式如下:

@ApiResponses({ @ApiResponse(code = 403, message = "无权限访问") })
public ResponseData login(@ApiParam(value = "登录参数", required = true) @RequestBody LoginQuery query) {

}

效果图如下:

image.png

  • code:响应状态码
  • message:状态码对应的说明

ApiImplicitParam和ApiImplicitParams

用于方法上,为单独的请求参数进行说明,使用方式如下:

 @ApiImplicitParams({
    	@ApiImplicitParam(name="uid", value="用户ID", required=true, paramType="query", dataType="String", defaultValue="1")
 })
 @GetMapping("/hello")
 public String hello(String uid) {
     return uid;
 }

效果图如下:

image.png

  • name:参数名,对应方法中单独的参数名称
  • value:参数中文说明
  • required:是否必填
  • paramType:参数类型,取值为path, query, body, header, form
  • dataType:参数数据类型
  • defaultValue:默认值

更多技术分享请关注微信公众号:猿天地

欢迎加入我的知识星球,一起交流技术,免费学习猿天地的课程(http://cxytiandi.com/course)

PS:目前星球中正在星主的带领下组队学习Spring Cloud,等你哦!

微信扫码加入猿天地知识星球

猿天地

发布了250 篇原创文章 · 获赞 89 · 访问量 42万+
展开阅读全文

没有更多推荐了,返回首页

©️2019 CSDN 皮肤主题: 大白 设计师: CSDN官方博客

分享到微信朋友圈

×

扫一扫,手机浏览