- 快速開始：
- 導(dǎo)入maven包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
- 在啟動類配置
# 主啟動類
@EnableSwagger2
1. Swagger簡介
1、前后端分離：
- Vue + Springboot 開發(fā)模式
- 后端時代：前端只用管理靜態(tài)頁面；html—>后端。模板引擎 JSP—>后端是主力
2、前后端分離時代：
- 前端 ：前端控制層、視圖層【前端團隊】
- 后端：后端控制層、服務(wù)層、數(shù)據(jù)訪問層【后端團隊】
- 前后端通過API進行交互【交互方式】
- 前后端相對獨立且松耦合；
- 前后端甚至可以部署在不同的服務(wù)器上
3、產(chǎn)生的問題：
- 前后端集成，前端或者后端無法做到“及時協(xié)商，盡早解決”，最終導(dǎo)致問題集中爆發(fā)
4、解決方案
- 首先定義schema [ 計劃的提綱 ]，并實時跟蹤最新的API，降低集成風(fēng)險
- 早些年：指定word計劃文檔
- 前后端分離：
- 前端測試后端接口：postman
- 后端提供接口，需要實施更新最新的消息及改動！
5、Swagger誕生
- 號稱世界上最流行的API框架
- Restful Api 文檔在線自動生成器 => API 文檔 與API 定義同步更新
- 直接運行，在線測試API
- 支持多種語言 （如：Java，PHP等）
- 官網(wǎng)：https://swagger.io/
2. 第一個Swagger程序
1、前期準備
SpringBoot集成Swagger => springfox，兩個jar包
- Springfox-swagger2
- swagger-springmvc
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、項目測試
- 創(chuàng)建一個普通的SpringBoot項目，支持web應(yīng)用
- 添加Maven依賴
- 編寫HelloController，測試確保運行成功！
package com.koko.controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@RequestMapping("/hello")
public String toHello(){
return "hello";
}
}
- SwaggerConfig配置類
package com.koko.config;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration //配置類
@EnableSwagger2// 開啟Swagger2的自動配置
public class SwaggerConfig {
}
- 測試：http://localhost:8080/swagger-ui.html
- 測試成功！
- 注意：報錯的話更改 spring-boot-starter-parent 版本
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.5.6</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
3. Swagger的配置
3.1 配置基本頁面
- SwaggerConfig配置類中
- Swagger實例Bean是Docket，所以通過配置Docket實例來配置Swaggger
- Docket 實例關(guān)聯(lián)上 apiInfo()
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}
- 可以通過apiInfo()屬性配置文檔信息
//配置文檔信息
private ApiInfo apiInfo() {
Contact contact = new Contact("koko", "http://xxx.xxx.com/聯(lián)系人訪問鏈接", "聯(lián)系人郵箱");
return new ApiInfo(
"Swagger學(xué)習(xí)", // 標題
"學(xué)習(xí)演示如何配置Swagger", // 描述
"v1.0", // 版本
"http://terms.service.url/組織鏈接", // 組織鏈接
contact, // 聯(lián)系人信息
"Apach 2.0 許可", // 許可
"許可鏈接", // 許可連接
new ArrayList<>()// 擴展
);
}
- 測試，訪問http://localhost:8080/swagger-ui.html
3.2 配置掃描接口
- SwaggerConfig配置類
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable設(shè)置是否啟動Swagger
.enable(false)
//通過.select()方法，去配置掃描接口
.select()
//RequestHandlerSelectors配置如何掃描接口
.apis(RequestHandlerSelectors.basePackage("com.koko.controller"))
// 配置如何通過path過濾,即這里只掃描請求以/koko開頭的接口
.paths(PathSelectors.ant("/koko/**"))
.build();
}
- RequestHandlerSelectors配置的一些方法
any() // 掃描所有，項目中的所有接口都會被掃描到
none() // 不掃描接口
// 通過方法上的注解掃描，如withMethodAnnotation(GetMapping.class)只掃描get請求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通過類上的注解掃描，如.withClassAnnotation(Controller.class)只掃描有controller注解的類中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根據(jù)包路徑掃描接口
- PathSelectors配置的一些方法
any() // 任何請求都掃描
none() // 任何請求都不掃描
regex(final String pathRegex) // 通過正則表達式控制
ant(final String antPattern) // 通過ant()控制
3.3 配置Swagger開關(guān)
- SwaggerConfig配置類中
@Bean
public Docket docket(Environment environment) {
// 設(shè)置要顯示swagger的環(huán)境
Profiles of = Profiles.of("dev", "test");
// 判斷當前是否處于該環(huán)境
// 通過 enable() 接收此參數(shù)判斷是否要顯示
boolean b = environment.acceptsProfiles(of);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//enable設(shè)置是否啟動Swagger
.enable(b)
//通過.select()方法，去配置掃描接口
.select()
//RequestHandlerSelectors配置如何掃描接口
.apis(RequestHandlerSelectors.basePackage("com.koko.controller"))
// 配置如何通過path過濾,即這里只掃描請求以/koko開頭的接口
.paths(PathSelectors.ant("/koko/**"))
.build();
}
- 通過enable()方法配置是否啟用swagger，如果是false，swagger將不能在瀏覽器中訪問了
- 如何動態(tài)配置當項目處于test、dev環(huán)境時顯示swagger，處于prod時不顯示？
- 設(shè)置配置文件
- application.properties
spring.profiles.active=dev
- application-dev.properties（開發(fā)環(huán)境）
server.port=8081
- application-pro.properties（發(fā)布環(huán)境）
server.port=8082
- 測試
- 訪問http://localhost:8081/swagger-ui.html時:（開發(fā)環(huán)境）——>頁面正常顯示
- 訪問http://localhost:8082/swagger-ui.html時：——>無法訪問！?。崿F(xiàn)環(huán)境改變的功能?。?！
3.4 配置API分組
1、實現(xiàn)步驟
- 在SwaggerConfig配置類的docket方法中
- 如果沒有配置分組，默認是default。通過groupName()方法即可配置分組
@Bean
public Docket docket(Environment environment) {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.groupName("hello") // 配置分組
// 省略配置....
}
- 配置多個分組方法：
- 配置多個docket
@Bean
public Docket docket1(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}
- 測試：http://localhost:8081/swagger-ui.html
3.5 常見注解
1、注解的簡單說明
- Swagger的所有注解定義在io.swagger.annotations包下（下面是常見的）
| Swagger注解 | 簡單說明 |
| — | — |
| [@Api(tags ](/Api(tags )
= “xxx模塊說明”) | 作用在模塊類上 |
| @ApiOperation(“xxx接口說明”) | 作用在接口方法上 |
| @ApiModel(“xxxPOJO說明”) | 作用在模型類上：如VO、BO |
| [@ApiModelProperty(value ](/ApiModelProperty(value )
= “xxx屬性說明”,hidden = true) | 作用在類方法和屬性上，hidden設(shè)置為true可以隱藏該屬性 |
| @ApiParam(“xxx參數(shù)說明”) | 作用在參數(shù)、方法和字段上，類似@ApiModelProperty |
2、舉例講解上述五個注解
- 以注釋了序號，可以和上述表對應(yīng)！
- HelloController頁面控制跳轉(zhuǎn)類
package com.koko.controller;
import com.koko.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@Api(tags = "1、模塊類")
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello(){
return "hello";
}
@PostMapping("/user")
public User user(){
return new User();
}
@ApiOperation("2、接口方法")
@GetMapping("/hello02")
public String toHello02(@ApiParam("5、接口中的參數(shù)、方法和字段") String username){
return "hello" + username;
}
}
- User實體類
package com.koko.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel("3、模型類(實體類)")
public class User {
@ApiModelProperty("4、屬性-用戶名")
public String username;
@ApiModelProperty("4、屬性-密碼")
public String password;
}
- 測試
- 在模塊類中
- 在實體類模型中
拓展：皮膚
- 默認的 ?**訪問 **http://localhost:8080/swagger-ui.html
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- bootstrap-ui ?**訪問 **http://localhost:8080/doc.html
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.1</version>
</dependency>
- Layui-ui ?**訪問 **http://localhost:8080/docs.html
<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>1.1.3</version>
</dependency>
- mg-ui ?**訪問 **http://localhost:8080/document.html
<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
<groupId>com.zyplayer</groupId>
<artifactId>swagger-mg-ui</artifactId>
<version>1.0.6</version>
</dependency>
總結(jié)文章來源：http://www.zghlxwxcb.cn/news/detail-756789.html
- 我們可以通過Swagger給一些比較難理解的屬性或者接口，增加注釋信息
- 接口文檔要實時更新
- 可以在線測試
Swagger是一個優(yōu)秀的工具，幾乎所有大公司都有使用它！
【注意點】在正式發(fā)布的時候，關(guān)閉Swagger?。?！處于安全考慮，也同時節(jié)省運行內(nèi)存?。。?span toymoban-style="hidden">文章來源地址http://www.zghlxwxcb.cn/news/detail-756789.html
到了這里，關(guān)于Swagger快速上手的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
