Swagger的使用(SpringBoot)
簡介
前後端分離
純後端時代:前端只用管理靜態頁面
前後端分離時代:
-
後端:後端控制層、服務層、數據庫訪問層
-
前端:前端控制層、視圖層
- 僞後端數據,json。(不需要後端,前端也可以跑起來)
-
前後端交互:通過api
-
前後端相互獨立,鬆耦合
-
前後端可以部署在不同的服務器
-
問題:
- 前後端集成聯調,前端人員和後端人員無法做到“及時協商,儘早解決”,最終導致問題集中爆發
-
解決方法:
- 首先制定計劃,實時更新最新api,降低集成風險
- 早些年使用word計劃文檔
- 前後端分離時代可以使用:前端測試後端接口:postman
swagger
- 號稱世界上最流行的API框架
- RestFul Api文檔在線自動生成工具–>api文檔和api定義同步更新
- 直接運行,可以在線測試Api接口
- 支持多種語言:java、php等等
官網:https://swagger.io/
在項目中使用
引入依賴
新建SpringBoot
項目,引入Swagger相關依賴:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.qianyu</groupId>
<artifactId>demo</artifactId>
<version>1.0-SNAPSHOT</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.6.RELEASE</version>
<relativePath/>
</parent>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
</project>
新建HelloWorld
- controller
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello() {
return "Hello World";
}
}
- 主類
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
- application.yml
server:
port: 9000
- Swagger配置類
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo());
}
// 配置Swagger的ApiInfo
private ApiInfo apiInfo() {
// 作者信息
Contact contact = new Contact("芊雨", "http://www.qianyucc.xyz/", "[email protected]");
return new ApiInfo(
"芊雨的博客API文檔",
"博客後端所有的api接口",
"v1.0.0",
"http://localhost:8886/",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
運行項目,在瀏覽器訪問http://localhost:9000/swagger-ui.html
,即可看到api文檔:
配置包掃描和只在開發環境生效
- 新建
application-dev.yml
和application-pro.yml
分別表示開發環境和生產環境 - 在
application.yml
中啓用開發環境
server:
port: 9000
spring:
profiles:
active: dev
- 修改配置類
@Bean
public Docket getDocket(Environment environment) {
// 如果在dev環境(開發環境)就開啓Swagger
boolean isDev = environment.acceptsProfiles(Profiles.of("dev"));
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.enable(isDev)
.select()
// 配置需要掃描的包
.apis(RequestHandlerSelectors.basePackage("com.qianyu.demo.controller"))
// 配置需要匹配的路徑
//.paths(PathSelectors.ant("/api/**"))
.build();
}
這時候只有在開發環境中訪問http://localhost:9000/swagger-ui.html
才能看到文檔內容
分組功能的實現
在Swagger配置類中,我們可以只用多個Docket
對象來完成分組,因爲在開發過程中每個人可能負責一個模塊,所以每個人都可以配置一個屬於自己的Docket
,並且在裏面實現個性化配置
@Bean
public Docket docket1() {
return new Docket(DocumentationType.SWAGGER_2).groupName("張三");
}
@Bean
public Docket docke2() {
return new Docket(DocumentationType.SWAGGER_2).groupName("李四");
}
@Bean
public Docket docket3() {
return new Docket(DocumentationType.SWAGGER_2).groupName("王五");
}
文檔註釋
默認情況下,只要接口的返回值中存在實體類,就會被掃描到Swagger中
@PostMapping("/user")
public User user() {
return new User();
}
如圖所示:
我們也可以使用註解來書寫註釋
@ApiModel("用戶實體類")
public class User {
@ApiModelProperty("用戶名")
private String username;
@ApiModelProperty("用戶id")
private Integer id;
@ApiModelProperty("用戶密碼")
private String password;
}
@ApiOperation("查詢用戶名是否存在")
@GetMapping("/demo")
public String demo(@ApiParam("用戶名") String username) {
return "res:" + username;
}
此時,在文檔上就會出現我們自定義的註釋: