Swagger注解详解

Swagger注解详解

一、 @Api

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

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

@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) {
         //
    }
}

二、 @ApiOperation

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

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

@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) {
 
      //处理
    }

三、@ApiImplicitParams

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

比如说：

@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);
	}

三、@ApiResponses

@ApiResponses用于表示一组响应

@ApiResponse

四、@ApiModel

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

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

@ApiModelProperty

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

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 
 
}