Swagger UI 簡介
Swagger UI允許任何人（無論您是開發團隊還是最終用戶）都可以可視化API資源並與之交互，而無需任何實現邏輯。它是根據您的OpenAPI（以前稱爲Swagger）規範自動生成的，具有可視化文檔，可簡化後端實現和客戶端使用。
SwaggerUI 特點
- 無依賴 UI可以在任何開發環境中使用，無論是本地還是在Web端中。
- 人性化 允許最終開發人員輕鬆地進行交互，並嘗試API公開的每個操作，以方便使用。
- 易於瀏覽 歸類整齊的文檔可快速查找並使用資源和端點。
- 所有瀏覽器支持 Swagger UI 在所有主要瀏覽器中均可使用，以適應各種可能的情況。
- 完全可定製 通過完整的源代碼訪問方式以所需方式設置和調整Swagger UI。
- 完整的OAS支持 可視化Swagger 2.0或OAS 3.0中定義的API。
前後端分離
Vue + SpringBoot
後端時代：前端只用管理靜態頁面; html==》後端。 模版引擎 JSP=>後端是主力
前後端分離時代：
- 後端：後端控制層、服務層、數據訪問層 【後端團隊】
- 前端：前端控制層、視圖層 【前端團隊】
- 僞造後端數據，json。在後端開發前數據以及存在，不需要後端，前端工程師依舊能將項目跑起來。
- 前後端如何交互？ ==>API
- 前後端相對獨立，松耦合；
- 前後端甚至可以部署在不同的服務器上。
產生一個問題
- 前後端集成聯調，前端人員和後端人員無法做到 “及時協商，儘早解決”，最終導致問題集中爆發；
解決方案：
- 首先指定schema[計劃的提綱]，實時更新最新的API，降低集成的風險。
- 早些年，制定Word計劃文檔
- 前後端分離：
- 前端測試後端接口使用：Postman工具。
- 後端提供接口：需要實時更新最新改動和消息。
Swagger登場
- 號稱世界上最流行的API框架。
- Restful API文檔在線自動生成工具 API文檔與API定義同步更新。
- 直接運行，可以在線測試API接口。
- 支持多種語言 如：Java 、PHP…
官網
在項目只能使用SwaggerUI
需要使用Springfox,配置的組件有
- Swagger 2
- UI 顯示頁面
springboot集成Swagger
1.idea新建SpringBoot-Web工程
2.POM文件中導入springfox-swagger2和springfox-swagger-ui
</dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
在這裏插入代碼片
3.編寫一個測試Controller 測試SpringBoot工程搭建是否成功。
4.配置Swagger 編寫Config文件
- 新建一個名爲config的Package包
- 創建SwaggerConfig配置類
- @Configuration 表明這是一個配置類
- @EnableSwagger2 開啓Swagger2
@Configuration
@EnableSwagger2 //開啓swagger2
public class SwaggerConfig {
}
5 、測試運行
瀏覽器打開 http://localhost:8080/swagger-ui.html
Swagger配置掃描接口
- 配置接口掃描與作者信息
使用Dokcet對象中的 .select()方法
/**
* 配置了Swagger 的Docket的bean實例,掃描接口的位置
* .apis
* RequestHandlerSelectors 配置swagger掃描接口的方式
* basePackage() 指定要掃描哪些包
* any() 全部都掃描
* none() 全部不掃描
* withClassAnnotation() 掃描類上的註解 參數是一個註解的反射對象
* withMethodAnnotation() 掃描包上的註解
* .paths
* PathSelectors 路徑掃描接口
* ant 配置以xxx 開頭的路徑
* @return
*/
@Bean
public Docket docket( ){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("James")
.select()
.apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller"))
//.paths(PathSelectors.ant("/hello/**"))
.build();//構建者模式
}
/**
* 配置Swagger信息 apiinfo
* @return
*/
private ApiInfo apiInfo(){
//配置作者信息
Contact DEFAULT_CONTACT = new Contact("James", "https://blog.csdn.net/zhanshixiang/", "[email protected]");
return new ApiInfo(
"James 的Swagger API文檔",
"碼出高效",
"v1.0",
"https://blog.csdn.net/zhanshixiang/",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
配置是否自動啓動Swagger
在開發環境開啓SwaggerUI ，生產環境關閉SwaggerUI 是因爲開發環境是內部人員，生產環境是客戶。爲了程序的安全性需要關閉SwagggerUI
/**
* 配置了Swagger 的Docket的bean實例,掃描接口的位置
* .apis
* RequestHandlerSelectors 配置swagger掃描接口的方式
* basePackage() 指定要掃描哪些包
* any() 全部都掃描
* none() 全部不掃描
* withClassAnnotation() 掃描類上的註解 參數是一個註解的反射對象
* withMethodAnnotation() 掃描包上的註解
* .paths
* PathSelectors 路徑掃描接口
* ant 配置以xxx 開頭的路徑
* @return
*/
@Bean
public Docket docket(Environment environment){
//設置要顯示的Swagger 環境
Profiles profiles =Profiles.of("dev","test");
/**
* 通過 environment.acceptsProfiles 返回的boolean值判斷是否處在自己所設定的環境中
*/
boolean flag = environment.acceptsProfiles(profiles);
System.out.println(flag);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("James")
//.enable(flag) //enable配置是否自動啓動swagger 如果爲False則爲不啓動，瀏覽器中不能訪問Swagger
.select()
.apis(RequestHandlerSelectors.basePackage("com.study.swagger.controller"))
//.paths(PathSelectors.ant("/hello/**"))
.build();//構建者模式
}
/**
* 配置Swagger信息 apiinfo
* @return
*/
private ApiInfo apiInfo(){
//配置作者信息
Contact DEFAULT_CONTACT = new Contact("James", "https://blog.csdn.net/zhanshixiang/", "[email protected]");
return new ApiInfo(
"James 的Swagger API文檔",
"碼出高效",
"v1.0",
"https://blog.csdn.net/zhanshixiang/",
DEFAULT_CONTACT,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
- 創建三個properties文件
application.properties
# 激活開發環境
spring.profiles.active=dev
application-dev.properties 開發環境
server.port=8082
application-properties 生產環境
server.port=8083
配置API分組
在協同開發時，每個開發人員都擁有一個屬於自己的API組
.groupName("test")
問題：如何配置多個分組？
編寫多個Docket 設置不同Docket方法名
/**
* 開發A組的接口
* @return
*/
@Bean
public Docket docketA(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("A");
}
/**
* 開發B組的接口
* @return
*/
@Bean
public Docket docketB(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("B");
}
/**
* 開發C組的接口
* @return
*/
@Bean
public Docket docketC(){
return new Docket(DocumentationType.SWAGGER_2)
.groupName("C");
}
訪問http://localhost:8080/swagger-ui.html
可以看到分組上有新的組了
配置實體類信息
@ApiModel("用戶實體類")
public class User implements Serializable {
@ApiModelProperty("用戶名")
private String username;
@ApiModelProperty("密碼")
private String password;
配置接口方法
@Api("Hello控制類")
@RestController
@RequestMapping("hello")
public class HelloController {
@GetMapping(value = "say")
public String hello() {
return "hello ";
}
/**
* 只要接口中,返回值中存在實體類，他就會被掃描到Swagger中
* @return
*/
@PostMapping(value = "/user")
public User user(){
return new User();
}
/**
* ApiOperation接口，不是放在類上的，是方法
* @return
*/
@ApiOperation("hello控制類")
@GetMapping(value = "/hello2")
public String hello2(@ApiParam("用戶名") String username){
return "hello"+username;
}
@ApiOperation("Post測試類")
@PostMapping(value = "/post")
public User post(@ApiParam("用戶") User user){
return user;
}
}
