首先給出學習的視訊傳送門：https://www.bilibili.com/video/BV1Y441197Lw

Swagger

學習目標：

• 瞭解Swagger的作用

• 瞭解前後端分離

• 在SpringBoot中整合Swagger

Swagger簡介

前後端分離 主流搭配：Vue + SpringBoot

後端時代： 前端只用管理靜態頁面；html==>後端。模板引擎 JSP => 後端主力

前後端分離時代：

• 後端：控制層、服務層、資料訪問層

• 前端：前端控制層、檢視層 （偽造後端資料 ---json）

• 前端如何跑起來？ ====> API

• 前後端相對獨立，鬆耦合

• 前後端甚至可以部署在不同的伺服器上；

產生問題：

• 前後端整合聯調，前端人員和後端人員無法做到 ”及時協商，今早解決“，最終導致問題集中爆發

解決方案：

• 首先指定 schema [計劃提綱] ，實時更新最新API ，降低整合的風險

• 早些年：制定word 計劃文件；

• 前後端分離：

  • 前端測試後端介面：postman

  • 後端提供介面，需要實時更新最新的訊息及改動

Swagger

• 號稱世界上最流行的Api 框架

• RestFul Api 文件線上自動生成工具 =>Api文件與APi定義同步更新

• 直接執行，可以線上測試Api 介面

• 支援多語言： （java \ php ...）

官網：https://swagger.io/

在專案中使用Swagger需要 匯入依賴 springfox-swagger2 、springfox-swagger-ui

• swagger2

• ui

SpringBoot整合Swagger

1、新建一個springboot 的 web專案

2、匯入相關依賴

 <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>
 
io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

3、編寫一個Hello的Get 介面

4、配置 Swagger ==》 Config

@Configuration
@EnableSwagger2  //開啟swagger2
public class SwaggerConfig {
    //配置swagger 的docket的bean例項
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
    //配置swagger資訊 =apiInfo
    private ApiInfo apiInfo(){
        //作者資訊
        Contact contact=new Contact("路上", "http://localhost:8080/hello",                           "[email protected]");
        return new ApiInfo("路上的Swagger API文件",
                "描述。。。",
                "版本1.0",
                "http://localhost:8080/hello",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

5、測試執行：http://localhost:8080/swagger-ui.html

Swagger配置掃描介面

Docket.select ()

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //RequestHandlerSelectors ,配置要掃描介面的方式

                //basePackage ：指定要掃描的包
               .apis(RequestHandlerSelectors.basePackage("com.example.swagger2.controller"))

                //ang :掃描全部
                .apis(RequestHandlerSelectors.any())

                //none :都不掃描
               .apis(RequestHandlerSelectors.none())

                //withClassAnnotation :掃描類上的註解
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))

                //withMethodAnnotation :掃描方法上的註解
               .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))

               //paths() 過濾什麼路徑
                .paths(PathSelectors.ant("/**"))
                .build();
    }

配置是否啟動Swagger

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否啟用swagger ，如果為false,則swagger不能在瀏覽器中訪問
                .enable(true)
                .select()           
                .paths(PathSelectors.ant("/**"))
                .build();
    }

問題： 怎樣設定Swagger在生產環境中使用，在釋出的時候不使用？

• 判斷是否生產環境 flag=false

• 注入 enable (flag)

1、新建application-dev.properties和application-pro.properties

2、分別在這兩個檔案中加入server.port=8000和server.port=8080

3、在application.properties中寫上spring.profiles.active=dev

4、在docket() 中獲取環境是否dev環境

@Bean
    public Docket docket(Environment env){//加入Environment來獲取配置中的東西

        //設定要顯示的swagger 環境
        
        Profiles profiles=Profiles.of("dev");
        //通過environment.acceptsProfiles判斷是否在自己設定的環境當中
        boolean flag=env.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()           
                .paths(PathSelectors.ant("/**"))
                .build();
    }

5、當訪問的埠為8000時才能訪問到swagger-ui的頁面，8080就不能。

配置APi的分組

.groupName("路上")

如何配置對個分組--->多個Docket例項即可

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
@Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
@Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }

實體類的註解

@ApiModel("使用者實體類 User")       //實體類註釋
public class User {
    @ApiModelProperty("使用者名稱")   //實體類欄位註釋
    public String username;
    @ApiModelProperty("密碼")
    public String password;
}

控制類的註解

//Api 介面註釋
@Api(tags="hello控制類")
@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello,lushang";
    }

    //ApiOperation介面註釋
    @ApiOperation("hello介面2")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("使用者名稱") String username){
        return "hello2";
    }

    //只要我們的介面中，返回值中存在實體類，他就會被掃描到 swagger 中
    @ApiOperation("post測試")
    @PostMapping("/user")
    public User  user(@ApiParam("使用者名稱+密碼") User user){
        return user;
    }   
}

總結：

• 我們可以通過Swagger給一些比較難理解的屬性或者介面，增加註解資訊

• 介面文件實時更新

• 可以線上測試

【注意點】 在正式釋出的時候，關閉Swagger~出於安全考慮。而且節省記憶體