官网:https://swagger.io/
- 上篇只是介绍了springboot如何继承swagger2,并没有详细的解释其api的使用,以下记录下使用规范
API使用:
作用范围 | API | 使用位置 |
---|---|---|
协议集描述 | @Api | 用于controller类上 |
协议描述 | @ApiOperation | 用在controller的方法上 |
非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
Response集 | @ApiResponses | 用在controller的方法上 |
Response | @ApiResponse | 用在 @ApiResponses里边 |
描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
@ApiImplicitParam() 内部参数:
属性 | 取值 | 作用 |
---|---|---|
paramType | 查询参数类型 | |
path | 以地址的形式提交数据 | |
query | 直接跟参数完成自动映射赋值 | |
body | 以流的形式提交 仅支持POST | |
header | 参数在request headers 里边提交 | |
form | 以form表单的形式提交 仅支持POST | |
dataType | 参数的数据类型 只作为标志说明,并没有实际验证 | |
Long | ||
String | ||
name | 接收参数名 | |
value | 接收参数的意义描述 | |
required | 参数是否必填 | |
true | 必填 | |
false | 非必填 | |
defaultValue | 默认值 |
-
多参数使用:@ApiImplicitParams({ @@ApiImplicitParam(),@ApiImplicitParam(),... })
给出几个使用示例 :
@ApiOperation("添加广告")
@ApiImplicitParams(@ApiImplicitParam(name = "haicheAd", value = "广告实体", required = true, paramType = "body", dataType = "HaicheAd"))
@PostMapping(value = "/add")
public void add(@RequestBody HaicheAd haicheAd) {
//HaicheAd 对象实体
}
@ApiOperation("查询广告列表页")
@ApiImplicitParams({
@ApiImplicitParam(name="index",value = "广告位置",paramType = "query",dataType = "String"),
@ApiImplicitParam(name="name",value = "广告名称",paramType = "query",dataType = "String"),
@ApiImplicitParam(name="del",value = "是否删除 1存在 0删除",paramType = "query",dataType = "int"),
@ApiImplicitParam(name="page",value = "页码",paramType = "query",dataType = "Integer"),
@ApiImplicitParam(name="pageSize",value = "页数",paramType = "query",dataType = "int")
})
@PostMapping(value = "/listBy")
public JsonFormat listBy(
@RequestParam(value = "index",required = false) String index,
@RequestParam(value = "name",required = false) String name,
@RequestParam(value = "del",required = false,defaultValue = "1") Integer del,
@RequestParam(value = "page",defaultValue = "1") Integer page,
@RequestParam(value = "pageSize",defaultValue = "10") Integer pageSize){
}
@ApiOperation("获取广告详情")
@ApiImplicitParams(
@ApiImplicitParam(name="id",value = "广告id",paramType = "path",required = true,dataType = "int"))
@GetMapping(value = "adInfo/{id}")
public JsonFormat getAdInfo(@PathVariable(value = "id") Integer id){
}