Swagger注釋API :@ApiModel

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)