1.API详细说明
注释汇总
作用范围 | API | 使用位置 |
对象属性 | @ApiModelProperty | 用在出入参数对象的字段上 |
协议集描述 | @Api | 用于controller类上 |
协议描述 | @ApiOperation | 用在controller的方法上 |
Response集 | @ApiResponses | 用在controller的方法上 |
Response | @ApiResponse | 用在 @ApiResponses里边 |
非对象参数集 | @ApiImplicitParams | 用在controller的方法上 |
非对象参数描述 | @ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
描述返回对象的意义 | @ApiModel | 用在返回对象类上 |
@RequestMapping此注解的推荐配置
value
method
produces
示例:
@ApiOperation("信息软删除")
@ApiResponses({ @ApiResponse(code = CommonStatus.OK, message = "操作成功"),
@ApiResponse(code = CommonStatus.EXCEPTION, message = "服务器内部异常"),
@ApiResponse(code = CommonStatus.FORBIDDEN, message = "权限不足") })
@ApiImplicitParams({ @ApiImplicitParam(paramType = "query", dataType = "Long", name = "id", value = "信息id", required = true) })
@RequestMapping(value = "/remove.json", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
public RestfulProtocol remove(Long id) {
@ApiModelProperty(value = "标题")
private String title;
@ApiImplicitParam
属性 | 取值 | 作用 |
paramType | | 查询参数类型 |
| path | 以地址的形式提交数据 |
| query | 直接跟参数完成自动映射赋值 |
| body | 以流的形式提交 仅支持POST |
| header | 参数在request headers 里边提交 |
| form | 以form表单的形式提交 仅支持POST |
dataType | | 参数的数据类型 只作为标志说明,并没有实际验证 |
| Long | |
| String | |
name | | 接收参数名 |
value | | 接收参数的意义描述 |
required | | 参数是否必填 |
| true | 必填 |
| false | 非必填 |
defaultValue | | 默认值 |
paramType 示例详解
path
@RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@PathVariable(name = "id") Long id
body
@ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息参数", required = true) })
@RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_JSON_VALUE)
@RequestBody MessageParam param
提交的参数是这个对象的一个json,然后会自动解析到对应的字段上去,也可以通过流的形式接收当前的请求数据,但是这个和上面的接收方式仅能使用一个(用@RequestBody之后流就会关闭了)
header
@ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) })
String idstr = request.getHeader("id");
if (StringUtils.isNumeric(idstr)) {
id = Long.parseLong(idstr);
}
Form
@ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) })
@RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE, consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
2.下面重点介绍@ApiModel
@ApiModel这个注解是比较重要的一个注解。因为在实际的开发过程中,我们知道了请求的地址后,我们更加重要的是关心这个接口的请求入参和返回值。
而对于@ApiModel这个注解,可以良好的展示出请求参数的含义和返回参数的含义。
源码展示:
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* Provides additional information about Swagger models.
* <p>
* Classes will be introspected automatically as they are used as types in operations,
* but you may want to manipulate the structure of the models.
*/
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface ApiModel {
String value() default "";
String description() default "";
Class<?> parent() default Void.class;
String discriminator() default "";
/**
* An array of the sub types inheriting from this model.
*/
Class<?>[] subTypes() default {};
/**
* Specifies a reference to the corresponding type definition, overrides any other metadata specified
*/
String reference() default "";
}
@ApiModel
这个注解
这个注解的是作用在类上面的,是用来描述类的一些基本信息的。下面,我们会逐个的进行讲解。
value属性
这个属性,提供的是类的一个备用名。如果我们不设置,那么默认情况下,将使用的是class
类的名字。
description属性
对于类,提供一个详细的描述信息
parent属性
这个属性,描述的是类的一些父类的信息。
discriminator属性
这个属性解释起来有些麻烦,因为这个类主要是体现出了断言当中。
subTypes属性
举个实例,如果我们此时有一个父类Animal
。同时,对于这个父类,我们的系统中有这个类的子类Cat
、Dog
、Pig
等。如果我们在我们的父类上,通过这个属性,指定了我们想要使用的子类的话,那么在生成Swagger
的文档的话,会自动的展示的是Animal
这个属性,但是在属性的字段中,会显示出子类的一些独有的属性,其实在这里,是不推荐使用的。因为这样会让别人认为,这些子类独有的属性,也是父类才有的。
假如我们有如下的几个类:
Pet类:
@ApiModel(value = "Pet", subTypes = {Cat.class},discriminator = "type")
public class Pet {
private long id;
private Category category;
private String name;
private List<String> photoUrls = new ArrayList<String>();
private List<Tag> tags = new ArrayList<Tag>();
@ApiModelProperty(value = "pet status in the store", allowableValues = "available,pending,sold")
private String status;
public long getId() {
return id;
}
public void setId(long id) {
this.id = id;
}
public Category getCategory() {
return category;
}
public void setCategory(Category category) {
this.category = category;
}
@ApiModelProperty(example = "doggie", required = true)
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public List<String> getPhotoUrls() {
return photoUrls;
}
public void setPhotoUrls(List<String> photoUrls) {
this.photoUrls = photoUrls;
}
public List<Tag> getTags() {
return tags;
}
public void setTags(List<Tag> tags) {
this.tags = tags;
}
public String getStatus() {
return status;
}
public void setStatus(String status) {
this.status = status;
}
private String type;
@ApiModelProperty(required = true)
public String getType() {
return type;
}
public void setType(String type) {
this.type = type;
}
}
Cat类
import javax.xml.bind.annotation.XmlRootElement;
public class Cat extends Pet {
String catBreed;
public String getCatBreed() {
return catBreed;
}
public void setCatBreed(String catBreed) {
this.catBreed = catBreed;
}
}
接口类
public interface OrderWebApi {
@RequestMapping(value = "/shen/testOne",method = RequestMethod.GET)
Result<Cat> getOrderDetail(@RequestParam("order_id") Integer orderId);
}
真正的Controller
类
@RestController
public class OrderWebController implements OrderWebApi {
@Override
public Result<Cat> getOrderDetail(Integer orderId) {
System.out.println(orderId);
OrderWebResVo orderWebResVo = new OrderWebResVo();
orderWebResVo.setAb(SexEnum.MAN);
orderWebResVo.setAge(20);
orderWebResVo.setMoney(4000L);
orderWebResVo.setMoneyOne(3000.0F);
orderWebResVo.setName("shen");
orderWebResVo.setSex(new Byte("1"));
Result<Cat> result = new Result<>();
result.setCode(20080);
result.setMessage("SUCCESS");
result.setData(new Cat());
return result;
}
}
Swagger
文档为
reference属性
指定对相应类型定义的引用,覆盖指定的任何其他元数据。
总结
这个注解主要讲解的是model
的信息信息。
更多ref:Swagger常用注解使用详解 (biancheng.net)