關(guān)于 Swagger

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

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

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

你可以通過一個(gè)文本編輯器來(lái)編輯 Swagger 文件，或者你也可以從你的代碼注釋中自動(dòng)生成。各種工具都可以使用 Swagger 文件來(lái)生成互動(dòng)的 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同級(jí)目錄） /**
* Swagger2配置類
* 在于Springboot集成時(shí)，需與application同目錄
* 通過注解@Configuration，讓Spring來(lái)加載該配置
* 通過注解@EnableSwagger2，來(lái)啟動(dòng)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才會(huì)被Swagger管理
.paths(PathSelectors.any()).build();
return docket;
}


/**
* 創(chuàng)建改API的基本信息（這些基本信息會(huì)展示在文檔頁(yè)面中）
* 訪問地址： http://項(xiàng)目實(shí)際地址/swagger-ui.html
* @return
*/
public ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2構(gòu)建RESTful APIs")
.description("了解更多請(qǐng)聯(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 文件對(duì)象
* @param request http請(qǐng)求
* @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：修飾整個(gè)類，描述Controller的作用
• @ApiOperation：描述一個(gè)類的一個(gè)方法，或者說(shuō)一個(gè)接口
• @ApiParam：單個(gè)參數(shù)描述
• @ApiModel：用對(duì)象來(lái)接收參數(shù)
• @ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
• @ApiResponse：HTTP響應(yīng)其中1個(gè)描述
• @ApiResponses：HTTP響應(yīng)整體描述
• @ApiIgnore：使用該注解忽略這個(gè)API
• @ApiError ：發(fā)生錯(cuò)誤返回的信息
• @ApiImplicitParam：一個(gè)請(qǐng)求參數(shù)
• @ApiImplicitParams：多個(gè)請(qǐng)求參數(shù)

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

?

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

總結(jié)

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

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