Swagger 註解使用

Swagger 註解

Swagger中的所有註解

       首先我們通過Swagger的源碼可以看到有很多的註解，下面這張截圖應該可以包括swagger的所有註解。

Swagger 常用註解的說明 

 第一類： 用在類上的註解  @Api   和@ ApiModel                                                                                                                           

註解名稱	使用說明
@Api	@Api 用在類上，說明該類的作用。可以標記一個 Controller 類作爲 Swagger 文檔資源,所以一般用在Controller接口中，在Swagger頁面上說明這個接口文檔
@ApiModel	使用在實體類上， 一般用來對接口入參來說明

 

 

 

 

@Api  使用 

1.  使用@Api 的代碼示例

@RestController
@RequestMapping("/xxxxxx")
@Api(tags = "密保問題")
public class xxxxController extends BaseController {
}

@RestController
@RequestMapping("/xxxxxx")
@Api(tags = "認識我們")
public class xxxxController extends BaseController {
}

@RestController
@RequestMapping("/xxxxxx")
@Api(tags = "設置密碼")
public class xxxxController extends BaseController {
}

2. 使用@Api 註解的效果 ，每個Controller接口進行說明該類的作用                                                                                                      

@ApiModel 使用 

1. 代碼示例

@ApiModel("設置密碼參數")
public class xxxParam {
}

第二類: 用來對參數進行說明的註解  @ ApiModelProperty  @ApiParam @ApiImplicitParam 和 @ApiImplicitParams

 

註解	使用說名	常用參數
@ ApiModelProperty	@ApiModelProperty()和@ApiModel 配套使用在實體類中， 用於字段，表示對 model 屬性的說明	value–字段說明  name–重寫屬性名字  dataType–重寫屬性類型  required–是否必填  example–舉例說明  hidden–隱藏
@ApiImplicitParam 和 @ApiImplicitParams	Api配套使用在Controller接口的方法上，對單獨的參數進行說明  這兩個註解一起使用，當只有一個參數修飾用@ApiImplicitParam，當有多個參參數用@ApiImplicitParams	name：參數名，對應方法中單獨的參數名稱。 value：參數中文說明。 required：是否必填。 paramType：參數類型，取值爲 path、query、body、header、form。 dataType：參數數據類型。 defaultValue：默認值。
@ApiParam	@ApiParam 用於 Controller 中方法的參數說明。使用方式代碼如下所示。	value：參數說明 required：是否必填

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

@ ApiModelProperty  代碼使用

@Data
@ApiModel( description = "新增用戶參數")
public class AddUserParam {
    @ApiModelProperty(value = "ID")
    private String id;
    @ApiModelProperty(value = "名稱")
    private String name;
    @ApiModelProperty(value = "年齡")
    private int age;
}

@ApiParam @ApiImplicitParam 代碼使用

@ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用戶ID", dataType = "string", paramType = "query", required = true, defaultValue = "1") })
@GetMapping("/user")
public UserDto getUser(@RequestParam("id") String id) {
    return new UserDto();
}

 @ApiParam 代碼使用

@PostMapping("/user")
public UserDto addUser(@ApiParam(value = "新增用戶參數", required = true) @RequestBody AddUserParam param) {
    System.err.println(param.getName());
    return new UserDto();
}

第三類： 用在方法上來標記方法的作用  @ApiOperation

註解	使用
@ApiOperation	@ApiOperation 用在 Controller 裏的方法上，說明方法的作用，每一個接口的定義。

 

 

 

@ApiOperation 代碼示例

@ApiOperation(value="新增用戶", notes="詳細描述")
public UserDto addUser(@ApiParam(value = "新增用戶參數", required = true) @RequestBody AddUserParam param) {

}