springboot-swagger
首先說下swagger是個什么東西感耙。
Swagger是一種Rest API的 簡單但強(qiáng)大的表示方式，標(biāo)準(zhǔn)的拌汇，語言無關(guān)艺谆，這種 表示方式不但人可讀，而且機(jī)器可讀仅政。 可以作為Rest API的交互式文檔松蒜，也可以作為Rest API的形式化的接口描述，生成客戶端和服務(wù)端的代碼
官網(wǎng)地址：https://swagger.io/
我的理解swagger就是一個基于接口和文檔于一體的玩意
- 首先已旧，下載swagger相關(guān)的依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
- 其次，在啟動方法添加相關(guān)的注解
@SpringBootApplication
// 這個注解必須的
@EnableSwagger2
@ComponentScan("com.yuxi")
@MapperScan("com.yuxi.dao")
public class SpringBootMain {
public static void main(String[] args) {
SpringApplication.run(SpringBootMain.class, args);
}
}
好了是不是很神奇召娜，就可以了你可以直接訪問：localhost:8888/swagger-ui.html
當(dāng)然這個確實是好了运褪，不過這樣的api接口文檔也太簡陋了，參數(shù)也m沒有說明玖瘸，誰知道你寫的什么意思呢秸讹？
接下來我們就看看swagger給我們提供的一系列的注解參數(shù)
- 最后，swagger注解說明
@Api：用在類上雅倒，說明該類的作用
@ApiOperation：用在方法上璃诀，說明方法的作用
@ApiImplicitParams：用在方法上包含一組參數(shù)說明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數(shù)的各個方面
paramType：參數(shù)放在哪個地方
header-->請求參數(shù)的獲让锵弧：@RequestHeader
query-->請求參數(shù)的獲攘踊丁：@RequestParam
path（用于restful接口）-->請求參數(shù)的獲茸厮小：@PathVariable
body（不常用）
form（不常用）
name：參數(shù)名
dataType：參數(shù)類型
required：參數(shù)是否必須傳
value：參數(shù)的意思
defaultValue：參數(shù)的默認(rèn)值
@ApiResponses：用于表示一組響應(yīng)
@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個錯誤的響應(yīng)信息
code：數(shù)字凿将，例如400
message：信息校套，例如"請求參數(shù)沒填好"
response：拋出異常的類
@ApiModel：描述一個Model的信息（這種一般用在post創(chuàng)建的時候，使用@RequestBody這樣的場景牧抵，請求參數(shù)無法使用@ApiImplicitParam注解進(jìn)行描述的時候）
@ApiModelProperty：描述一個model的屬性
當(dāng)然這些注解是我參考的笛匙，參考文章為：http://www.cnblogs.com/java-zhao/p/5348113.html
這個是我使用注解的代碼塊：
@ApiOperation("根據(jù)賬單ID查詢")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "path", name = "id", value = "訂單ID", dataType = "int")
})
@RequestMapping(value = "/{id}", method = RequestMethod.GET)
@ApiResponses(value = {
@ApiResponse(code = 401, message = "參數(shù)錯誤"),
@ApiResponse(code = 404, message = "路徑不正確"),
@ApiResponse(code = 501, message = "內(nèi)部錯誤"),
@ApiResponse(code = 200, message = "正常返回")
})
public Account getAccountById(@PathVariable("id") int id) {
return accountService.findAccountById(id);
}
想看更多源碼地址請參考：
http://git.oschina.net/xiaoyuxi/springbootlearning
