swagger 2 笔记

因为之前的公司接口文档都是采用facebook的graphql文档，没用过swagger，所以做下几个简单的记录

@Api(value = "") 作用在controller上面，表示当前类是swagger的管理对象，value是说明

@RestController
@Api(value = "标签管理")
@RequestMapping("/xxx")
@Slf4j
public class TagsController {
}

@ApiOperation() 用于方法；表示一个http请求的操作 
value用于方法描述 
notes用于提示内容 

@RestController
@Api(value = "标签管理")
@RequestMapping("/xxx")
@Slf4j
public class TagsController {
   @ApiOperation(value = "给实例增加标签",notes = "提示内容")
   @PostMapping("/xxx")
   public ResultVo savetag(@RequestBody TagBo tagBo) throws GeneralBusException {
       return null;
   }
}

@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等） 
name–参数名 
value–参数说明 
required–是否必填

@RestController
@Api(value = "标签管理")
@RequestMapping("/xxx")
@Slf4j
public class TagsController {
   @ApiOperation(value = "给实例增加标签",notes = "提示内容")
   @PostMapping("/xxx")
   public ResultVo savetag(@ApiParam(name="taBo",value="说明",required=true) @RequestBody TagBo tagBo) throws GeneralBusException {       return null;
   }
}

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收 
value–表示对象名 
description–描述 

@ApiModel(value = "标签详情bo",description = "描述")
public class TagBo extends BaseBo{}

@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 
value–字段说明 
name–重写属性名字 
dataType–重写属性类型 
required–是否必填 
example–举例说明 
hidden–隐藏

@ApiModel(value = "标签详情bo",description = "描述")
public class TagBo extends BaseBo{
    @ApiModelProperty(name = "tag", value = "所属标签，支持逗号隔开", dataType = "String",example = "123456",hidden = false)    private String tag;
}

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上 

@ApiImplicitParam() 用于方法 
表示单独的请求参数 
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam 
name–参数ming 
value–参数说明 
dataType–数据类型 
paramType–参数类型 
example–举例说明

            @ApiOperation(value = "删除实例标签")
	    @ApiImplicitParam(name = "id", value = "id", required = true, dataType = "Long")           
	    @GetMapping("/xxx")
	    public ResultVo delete(@RequestParam("id") Long id) {
	        return null;
	    }

	    @ApiOperation(value = "查询实例下所有标签")
	    @ApiImplicitParams({
	 	@ApiImplicitParam(name = "targetId", value = "实例id", required = true, dataType = "Long"),
	 	@ApiImplicitParam(name = "type", value = "类型", required = true, dataType = "String"),
	 	@ApiImplicitParam(name = "categoryId", value = "分类id", required = true, dataType = "Long")
	    })
	    @GetMapping("/xxx")
	    public ResultVo findTagByTargetId(@NotNull@RequestParam("targetId") Long targetId,
	    		@NotEmpty@RequestParam("type") String type,
	    		@NotNull@RequestParam("categoryId") Long categoryId) {
	        
	 		return null;
	    }