Swagger文档API学习 |
您所在的位置：网站首页 › @apimodel › Swagger文档API学习 |
Swagger文档API学习
|
Swagger文档API学习–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. ** 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 { /** * Provide an alternative name for the model. * * By default, the class name is used. */ String value() default ""; /** * Provide a longer description of the class. */ String description() default ""; /** * Provide a superclass for the model to allow describing inheritance. */ Class parent() default Void.class; /** * Supports model inheritance and polymorphism. * * This is the name of the field used as a discriminator. Based on this field, * it would be possible to assert which sub type needs to be used. */ 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 photoUrls = new ArrayList(); private List tags = new ArrayList(); @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 getPhotoUrls() { return photoUrls; } public void setPhotoUrls(List photoUrls) { this.photoUrls = photoUrls; } public List getTags() { return tags; } public void setTags(List 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 getOrderDetail(@RequestParam("order_id") Integer orderId); }真正的Controller类 @RestController public class OrderWebController implements OrderWebApi { @Override public Result 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 result = new Result(); result.setCode(20080); result.setMessage("SUCCESS"); result.setData(new Cat()); return result; } }但是真正的Swagger文档为
指定对相应类型定义的引用，覆盖指定的任何其他元数据。 总结这个注解主要讲解的是model的信息信息，但是对于POJO中的内在属性需要参考下一篇文章讲解的@ApiModelProperty属性。 转载请注明来源，欢迎指出任何有错误或不够清晰的表达。可以邮件至 [email protected] |
【本文地址】
今日新闻 |
推荐新闻 |