swagger注解

Swagger注解详解

1.1 @Api

用在类上，说明该类的作用

比如说：@Api(value = “UserController”, description = “用户相关api”)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

@Api ( value = "物料" ) @Controller @RequestMapping ( "material" ) public class MaterialController {         @Resource      protected MaterialService materialService ;        @ApiOperation ( httpMethod = "POST" , value = "创建物料" )      @RequestMapping ( "service/create" )      @ResponseBody      public ResponseResult <String> create ( @RequestBody Material material ) {          //      } }

 

1.2 @ApiOperation

用在方法上，说明方法的作用

比如说：
@ApiOperation(value = “查找用户”, notes = “查找用户”, httpMethod = “GET”, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)

1 2 3 4 5 6 7 8 9 10 11 12 13

@ApiOperation ( httpMethod = "POST" , value = "查询物料" )      @RequestMapping ( "service/findByPage" )      @ResponseBody      public ResponseResult < PageView <Material> > findByPage ( @ApiParam ( value = "所在页" , defaultValue = "0" ) @RequestParam ( defaultValue = "0" ) int pageNo , @ApiParam ( value = "每页数量" , defaultValue = "10" ) @RequestParam ( defaultValue = "10" ) int pageSize , @ApiParam ( value = "查询条件,属性名请参考 Material" ) @RequestBody ( required = false ) List <QueryParam> params ) {          //处理      }

 

 

1.3  @ApiImplicitParams

用在方法上包含一组参数说明
paramType：参数放在哪个地方
header–>请求参数的获取：@RequestHeader
query–>请求参数的获取：@RequestParam
path（用于restful接口）–>请求参数的获取：@PathVariable
body（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值

比如说：

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

@ApiOperation ( httpMethod = "GET" , value = "获取店铺列表" , response = ResponseResult . class , notes = "实现方式可以用get请求,直接传当前页以及页码大小以及排序等：http://localhost:8888/shop/find?sort=cellphone,asc&sort=shopFullName,desc&page=1&size=10" ) @ApiImplicitParams ( { @ApiImplicitParam ( name = "province" , required = false , value = "省" , paramType = "query" , dataType = "String" ) , @ApiImplicitParam ( name = "city" , required = false , value = "市" , paramType = "query" , dataType = "String" ) , @ApiImplicitParam ( name = "county" , required = false , value = "县" , paramType = "query" , dataType = "String" ) ,          @ApiImplicitParam ( name = "pageable" , required = false , value = "分页，排序对象" , paramType = "body" , dataType = "Pageable" ) } ) @ResponseBody @RequestMapping ( value = { "/findAll" } , method = { RequestMethod . GET , RequestMethod . POST } ) public ResponseResult < Page <ShopInfo> > findAll ( @RequestParam ( required = false ) String province , @RequestParam ( required = false ) String city , @RequestParam ( required = false ) String county , @PageableDefault ( sort = { "id" } , direction = Sort . Direction . ASC ) Pageable pageable ) {                  //处理逻辑 return ResponseResult . success ( shopList ) ; }

 

1.4 @ApiResponses

@ApiResponses用于表示一组响应

 

1.5  @ApiResponse

 

 

1.6  @ApiModel

描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModel(value = “用户实体类”)

1 2 3 4 5 6

@ApiModel ( value = "优惠劵信息" ) @Entity @Table ( name = "coupon_info" ) public class CouponInfo implements Serializable {   }

 

1.7  @ApiModelProperty

描述一个model的属性
@ApiModelProperty(value = “登录用户”)

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

package com . souvc . entity ;   import io . swagger . annotations . ApiModel ; import io . swagger . annotations . ApiModelProperty ; import java . io . Serializable ; import java . util . Date ;   @ApiModel ( value = "物料" ) public class Material implements Serializable {        @ApiModelProperty ( "主键" )      private String id ;        @ApiModelProperty ( "项目ID" )      private String projectId ;        @ApiModelProperty ( "公司Id" )      private String companyId ;        //get,set   }