作者：追夢1819
原文：https://www.cnblogs.com/yanfei1819/p/11007470.html
版權聲明：本文為博主原創文章，轉載請附上博文鏈接！
引言
前面的十四篇文介紹了 SpringBoot 的一些基本和常用的功能。后面，我們將介紹 SpringBoot 的高級的功能、框架原理以及使用技巧。
一個項目組可能由前端、后端、安卓、IOS等眾多的開發人員或者眾多開發團隊組成。內部的 API 共同成本巨大。主要體現在幾個方面：
- 接口多且復雜；
- 細節之處繁雜：通訊協議、參數、返回值、接口說明、路徑等；
- 接口的維護。功能接口是隨着時間迭代升級的，因此這增加了接口文檔的管理成本。
因此，團隊內部的溝通，一直都是開發人員的一個痛點。而手動編寫 api 文檔，不僅效率低，而且容易遺漏、不能及時同步更新。swagger 框架很好的解決了此問題。
swagger簡介
swagger 優雅的解決了這個問題。它是一個功能強大的API框架，它的集成非常簡單，不僅提供了在線文檔的查閱，而且還提供了在線文檔的測試。swagger 是一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步。swagger 讓部署管理和使用功能強大的 API 從未如此簡單。
版本信息
- JDK：1.8
- SpringBoot ：2.1.4.RELEASE
- maven：3.3.9
- swagger2：2.4.0
- swagger-bootstrap-ui：1.7
- IDEA：2019.1.1
swagger 常用注解
swagger 通過注解表明該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。
-
@Api：修飾整個類，描述Controller的作用
-
@ApiOperation：描述一個類的一個方法，或者說一個接口
-
@ApiParam：單個參數描述
-
@ApiModel：用對象來接收參數
-
@ApiProperty：用對象接收參數時，描述對象的一個字段
-
@ApiResponse：HTTP響應其中1個描述
-
@ApiResponses：HTTP響應整體描述
-
@ApiIgnore：使用該注解忽略這個API
-
@ApiError ：發生錯誤返回的信息
-
@ApiImplicitParam 一個參數
-
@ApiImplicitParams 多個參數
swagger使用
為了更加形象說明 swagger 的使用，下面創建一個實例項目以作演示。
首先，引入 maven 依賴：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- swagger用於定義API文檔 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
然后，配置 swagger：
package com.yanfei1819.swaggerdemo;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.yanfei1819.swaggerdemo.controller"))
// .paths(AppUtility.isProd() ? PathSelectors.none() : PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("測試swagger")
.description("展示swagger界面")
.termsOfServiceUrl("http://localhost:8084/swagger-ui.html")
.contact(new Contact("追夢1819", "http://localhost:8084/swagger-ui.html", "xxx@163.com"))
.version("1.0")
.build();
}
}
下一步，創建幾個測試方法：
package com.yanfei1819.swaggerdemo.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.annotations.ApiIgnore;
/**
* Created by 追夢1819 on 2019-05-06.
*/
@Controller
@RequestMapping("/swagger-a")
@Api(value = "測試第一個controller")
public class SwaggerAController {
@ApiOperation(value = "controllerA的測試方法一",notes = "controllerA的測試方法一")
@GetMapping("/test1")
public void test1(){}
@ApiOperation(value = "controllerA的測試方法二",notes = "controllerA的測試方法二")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "用戶姓名", required = true, dataType = "String"),
@ApiImplicitParam(name = "password", value = "用戶密碼", required = true, dataType = "String")
})
@PostMapping("/test2")
public void test2(String name,String password){}
@ApiOperation(value = "controllerA的測試方法三",notes = "controllerA的測試方法三")
@ApiImplicitParam(name = "name", value = "用戶姓名", required = true, dataType = "String")
@GetMapping("/test3")
public void test3(String name){}
// 該接口忽略
@ApiIgnore
@GetMapping("/test4")
public void test4(String name){}
}
最后，訪問：http://localhost:8084/swagger-ui.htm，生成的相應的界面：
優化swagger界面
swagger 原生的界面談不上美觀。swagger-bootstrap-ui是springfox-swagger的增強UI實現，為Java開發者在使用 swagger 的時候，能擁有一份簡潔、強大的接口文檔體驗。
swagger-bootstrap-ui提供兩大核心功能：文檔說明 和 在線調試，以下作說明。
在以上實例的基礎上，引入maven依賴即可：
<!--美化swagger-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.7</version>
</dependency>
然后，訪問 http://localhost:8084/doc.html，看看效果：
總結
其實對於作者來說，我並不喜歡這種這種編碼風格。雖然生成了 spi 文檔，但是其注解對接口的污染較大。算是事有利弊吧，主要衡量利弊輕重。
源碼：我的GitHub
