Swagger配置詳解

Swagger

一、Swagger簡介

1.1、前后端發展過程

1. 后端時代：前端只管理靜態頁面 html ；后端則是主力，會使用模板引擎JSP

2. 前后端分離時代：

• 后端負責：后端控制層，服務層，數據訪問層

• 前端負責：前端控制層（vue），視圖層

  • 前端可以偽造后端數據，無需后端，前端頁面依舊可以運行

• 前后端交互：API；前端頁面調用API獲取后台數據，后台提供接口，按需求提供數據

  • 這樣前后端相對獨立。松耦合

  • 前后端可以部署在不同的服務器上

1.2、前后端分離產生的問題及解決

前后端集成聯調，前后端人員無法做到“及時協商，盡早解決”，最終導致問題集中爆發。

解決方案：

• 首先指定schema（計划提綱），實時更新API，降低集成風險

• 早年制定 word 計划文檔

• 前后端分離：

  • 前端測試后端接口：postman

  • 后端提供接口，需要實時更新最新的消息及改動

1.3、世界上最流行的API框架：Swagger

Swagger的優勢：

• 是 RestFul API 文檔在線自動生成工具：API文檔與API定義同步更新

• 直接運行，可以在線測試API接口

• 支持多種語言：（java、Php......）

Swagger官網：https://swagger.io/

Swagger依賴：

• swagger2

• UI

二、SpringBoot集成Swagger

2.1、新建SpringBoot-web項目

2.2、導入依賴

• 進入Maven依賴：https://mvnrepository.com

• 搜索：springfox-swag

  • 前兩個依賴分別為 swagger2 和 UI

• 導入依賴

<!-- swagger2依賴 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- ui依賴 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2.3、編寫一個接口

接口概念：這個接口和 interface 不同，是網絡接口，前端通過此接口輸入信息，獲取數據。因此此接口都有對應的網絡地址，有 @RequestMapping

 @RequestMapping("/getAllTeacher")
    @ResponseBody
    public List<Staff> getAllTeacher(){
        List<Staff> list = ss.getAllTeacher();
        return list;
   }

2.4、配置Swagger

@Configuration
@EnableSwagger2  //開啟swagger2
public class SwaggerConfig {
}

2.5、運行測試

• 運行項目

• 輸入網址：http://localhost:8080/swagger-ui.html，顯示頁面

三、配置Swagger

3.1、swagger的bean實例為：Docket

public class Docket implements DocumentationPlugin {
    
    //Docket中有一個 ApiInfo 的屬性，用來設置Info信息
    private ApiInfo apiInfo = ApiInfo.DEFAULT;
    
    //對應設置 ApiInfo 的方法
    public Docket apiInfo(ApiInfo apiInfo) {
    this.apiInfo = defaultIfAbsent(apiInfo, apiInfo);
    return this;
 }
    
}

3.2、接口信息設置：ApiInfo

public class ApiInfo {
    
    //ApiInfo設置了默認的 ApiInfo 值
    public static final ApiInfo DEFAULT = new ApiInfo(
        //title：標題
        "Api Documentation",
        //description：API描述
        "Api Documentation", 
        //version:版本
        "1.0", 
        "urn:tos",
        //作者信息，是個引用數據類型，要自己new
          DEFAULT_CONTACT,
        "Apache 2.0", 
        "http://www.apache.org/licenses/LICENSE-2.0", 
        new ArrayList<VendorExtension>());
}

3.2、配置swagger頁面的信息

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置了Swagger的Docter的bean實例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
   }
​
    private ApiInfo apiInfo(){
​
        //作者信息
        Contact contact = new Contact("java大數據班","","[e-mail]");
​
        return new ApiInfo(
                "第三階段項目",
                "SpringBoot綜合練習",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
   }
}

再次啟動運行后，swagger頁面的默認配置信息被我們自己寫的替代

四、swagger配置掃描接口及分組

4.1、swagger配置掃描接口

生成Docket對象時，設置生成API，方法為：

• .select() .apis(RequestHandlerselector.配置方式) .build()

• apis()內部的 RequestHandlerselectors，配置要掃描接口的方式

  • basePackage("包名"):指定要掃描的包指定掃描方式

  • any():掃描全部

  • none( ):不掃描

  • withclassAnnotation:掃描類上的注解，參數是一個注解的反射對象

  • withMethodAnnotation:掃描方法上的注解

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置了Swagger的Docter的bean實例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
                //選擇接口
               .select()
                //選擇接口
               .apis(RequestHandlerSelectors.basePackage("com.hxzy.course.controller"))
                //build()一般表示工廠設計模式
               .build();
   }
​
    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("梁鑫","","[e-mail]");
        return new ApiInfo(
                "第三階段項目",
                "SpringBoot綜合練習",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
   }
}

4.2、swagger配置分組

分組步驟：

• 創建不同的 Docket 對象

• 使用groupName(組名)方法為不同的Docket組別命名

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //配置了Swagger的Docter的bean實例
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
            //為分組命名
               .groupName("梁鑫")
               .apiInfo(apiInfo1())
                //選擇接口
               .select()
                //選擇接口
               .apis(RequestHandlerSelectors.basePackage("com.hxzy.course.controller"))
                //build()一般表示工廠設計模式
               .build();
   }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
               .groupName("賀景深")
               .apiInfo(apiInfo2())
                //選擇接口
               .select()
                //選擇接口
               .apis(RequestHandlerSelectors.basePackage("com.hxzy.booking.controller"))
                //build()一般表示工廠設計模式
               .build();
   }
    private ApiInfo apiInfo1(){
        //作者信息
        Contact contact = new Contact("梁鑫","","[e-mail]");
        return new ApiInfo(
                "第三階段項目",
                "SpringBoot綜合練習",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
   }
    private ApiInfo apiInfo2(){
        //作者信息
        Contact contact = new Contact("賀景深","","[e-mail]");
        return new ApiInfo(
                "第三階段項目",
                "SpringBoot綜合練習",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
   }
}

4.3、swagger配置是否啟動Docket

.enable():方法

• .enable(true) 表示啟動Docket，默認就是true

• .enable(false)表示不啟動Docket

public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
            .enable(false)
            //為分組命名
               .groupName("梁鑫")
               .apiInfo(apiInfo1())
                //選擇接口
               .select()
                //選擇接口
               .apis(RequestHandlerSelectors.basePackage("com.hxzy.course.controller"))
                //build()一般表示工廠設計模式
               .build();
   }