關(guān)于 Swagger

Swagger能成為最受歡迎的REST APIs文檔生成工具之一，有以下幾個原因：

• Swagger 可以生成一個具有互動性的API控制臺，開發(fā)者可以用來快速學習和嘗試API。
• Swagger 可以生成客戶端SDK代碼用于各種不同的平臺上的實現(xiàn)。
• Swagger 文件可以在許多不同的平臺上從代碼注釋中自動生成。
• Swagger 有一個強大的社區(qū)，里面有許多強悍的貢獻者。

Swagger 文檔提供了一個方法，使我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了比如 names、order 等 API 信息。

你可以通過一個文本編輯器來編輯 Swagger 文件，或者你也可以從你的代碼注釋中自動生成。各種工具都可以使用 Swagger 文件來生成互動的 API 文檔。

下面我們開始在Spring Boot中使用Swagger2構(gòu)建RESTful APIs

第一步，在pom.xml中加入Swagger2的依賴

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>

第二步，創(chuàng)建Swagger2配置類（注意配置類須與application同級目錄） /**
* Swagger2配置類
* 在于Springboot集成時，需與application同目錄
* 通過注解@Configuration，讓Spring來加載該配置
* 通過注解@EnableSwagger2，來啟動swagger2
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* 創(chuàng)建API應(yīng)用
*
* @return
*/
@Bean
public Docket createRestApi() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.web"))//注：該路徑指定為需要加載Swagger的路徑，只有路徑中的API才會被Swagger管理
.paths(PathSelectors.any()).build();
return docket;
}


/**
* 創(chuàng)建改API的基本信息（這些基本信息會展示在文檔頁面中）
* 訪問地址： http://項目實際地址/swagger-ui.html
* @return
*/
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2構(gòu)建RESTful APIs")
.description("了解更多請聯(lián)系：Misme")
.termsOfServiceUrl("http://www.cnblogs.com/MisMe/")
.contact("Misme")
.version("1.0")
.build();
}
}

第三步，添加文檔內(nèi)容，在需要的地方添加注解
@Api("ChatInfoController|圖片和音頻上傳控制器類")
@RestController
public class ChatInfoController {

/**
* 上傳圖片接口
* @param attach 文件對象
* @param request http請求
* @return imgSrc：上傳后圖片文件的路徑
*/
@ApiOperation(value = "上傳圖片",notes = "文件不能超過20M大小，后綴名為png，jpg，gif")
@RequestMapping(value = "/uploadImg",method = RequestMethod.POST)
@ResponseBody
public String uploadImg(@RequestParam("file") MultipartFile attach, HttpServletRequest request) {
System.out.println("上傳圖片");
return "具體方法";
}
}

注解詳解：

• @Api：修飾整個類，描述Controller的作用
• @ApiOperation：描述一個類的一個方法，或者說一個接口
• @ApiParam：單個參數(shù)描述
• @ApiModel：用對象來接收參數(shù)
• @ApiProperty：用對象接收參數(shù)時，描述對象的一個字段
• @ApiResponse：HTTP響應(yīng)其中1個描述
• @ApiResponses：HTTP響應(yīng)整體描述
• @ApiIgnore：使用該注解忽略這個API
• @ApiError ：發(fā)生錯誤返回的信息
• @ApiImplicitParam：一個請求參數(shù)
• @ApiImplicitParams：多個請求參數(shù)

第四步，啟動后訪問：?http://項目實際地址/swagger-ui.html，即可看見Swagger的管理頁面，如果未看見管理的API請檢查第二步的 apis(RequestHandlerSelectors.basePackage("com.web")) 路徑是否正確；

?

轉(zhuǎn)載于:https://www.cnblogs.com/MisMe/p/10778756.html

總結(jié)

以上是生活随笔為你收集整理的Spring Boot中使用Swagger2构建RESTful APIs的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。