一、swagger常用註解
1、與模型相關的註解
兩個註解：
- @ApiModel：用在模型類上，對模型類做註釋；
- @ApiModelProperty：用在屬性上，對屬性做註釋
2、與接口相關的註解
六個註解：
- @Api：用在controller上，對controller進行註釋；
- @ApiOperation：用在API方法上，對該API做註釋，說明API的作用；
- @ApiImplicitParams：用來包含API的一組參數註解，可以簡單的理解爲參數註解的集合聲明；
- @ApiImplicitParam：用在@ApiImplicitParams註解中，也可以單獨使用，說明一個請求參數的各個方面，該註解包含的常用選項有：
- paramType：參數所放置的地方，包含query、header、path、body以及form，最常用的是前四個。
- name：參數名；
- dataType：參數類型，可以是基礎數據類型，也可以是一個class；
- required：參數是否必須傳；
- value：參數的註釋，說明參數的意義；
- defaultValue：參數的默認值；
- @ApiResponses：通常用來包含接口的一組響應註解，可以簡單的理解爲響應註解的集合聲明；
- @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
- code：即httpCode，例如400
- message：信息，例如"請求參數沒填好"
二、幾個注意點：
- 爲了在swagger-ui上看到輸出，至少需要兩個註解：@Api和@ApiOperation
- 即使只有一個@ApiResponse，也需要使用@ApiResponses包住
- 對於@ApiImplicitParam的paramType：query、form域中的值需要使用@RequestParam獲取， header域中的值需要使用@RequestHeader來獲取，path域中的值需要使用@PathVariable來獲取，body域中的值使用@RequestBody來獲取，否則可能出錯；而且如果paramType是body，name就不能是body，否則有問題，與官方文檔中的“If paramType is "body", the name should be "body"不符。