0
点赞
收藏
分享

微信扫一扫

Swagger注释API :@ApiModel

回溯 2022-06-01 阅读 30

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​​文档为

Swagger注释API :@ApiModel_json

reference属性

  指定对相应类型定义的引用,覆盖指定的任何其他元数据。

总结

  这个注解主要讲解的是​​model​​的信息信息。

更多ref:​​Swagger常用注解使用详解 (biancheng.net)​​


举报

相关推荐

0 条评论