介面測試、管理神器-Swagger

Swagger

1. 號稱世界上最流行的API框架。
2. RestFul API文件線上自動生成工具->Api文件與API定義同步更新。
3. 直接執行，可以線上測試API介面。

swagger_demo的地址
官網：https://swagger.io/

在專案中使用Swagger需要springbox;

1. swagger2
2. ui

SpringBoot整合Swagger
1,新建一個springBoot Web專案
2，匯入相關依賴

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



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

3，編寫一個Hello工程。
4，編寫Swagger==>Config

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

5，測試執行

http://localhost:8080/swagger-ui.html#/hello-controller

配置Swagger
Swagger的bean例項Docket；

package com.shuang.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@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 contack=new Contact("江爽","https://www.shishuangzhi.xyz","2894247242@qq.com");

        return new ApiInfo(
                "爽寶的Swagger API文件",
                "看到這個demo的人，能教我追妹子嗎，有償，微訊號：js13617293003",
                "1.0",
                "https://www.shishuangzhi.xyz",
                contack,
                "Apache 2.0",
                "http://www.apache.org/license/LICENSE-2.0",
                 new ArrayList()
        );
    }


}

Swagger配置掃描介面
Docket.select()

//配置了swagger的docket的bean例項
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //RequestHandlerSelectors，配置要掃描介面的方式
            //basePackage:指定要掃描的包
            //any():掃描全部
            //none():不掃描
            //withclassAnnotation:掃描類上的註解
            .apis(RequestHandlerSelectors.basePackage("com.shuang.controller"))
            //paths()，過濾什麼路徑
            .paths(PathSelectors.ant("/shuang/**"))
            .build();
}

我只希望我的Swagger在生產環境中使用，在釋出的時候不使用？
1）判斷是不是生產環境 flag=false
2）注入enable(flag)

//配置了swagger的docket的bean例項
//core.env結尾的
@Bean
public Docket docket(Environment environment){

    //設定要顯示的Swagger環境
    Profiles profiles=Profiles.of("dev","test");

    //獲取專案的環境
    //通過environment.acceptsProfiles判斷是否處於自己設定的環境中。
    boolean flag = environment.acceptsProfiles(profiles);


    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .enable(flag)//enable是否啟動Swagger,如果為false,則Swagger不能在瀏覽器中訪問。
            .select()
            //RequestHandlerSelectors，配置要掃描介面的方式
            //basePackage:指定要掃描的包
            //any():掃描全部
            //none():不掃描
            //withclassAnnotation:掃描類上的註解
            .apis(RequestHandlerSelectors.basePackage("com.shuang.controller"))
            //paths()，過濾什麼路徑
            .paths(PathSelectors.ant("/shuang/**"))
            .build();
}

配置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");
}
@Bean
public Docket docket4(){
    return new Docket(DocumentationType.SWAGGER_2).groupName("D");
}

實體類

package com.shuang.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("使用者實體類")
public class User {

    @ApiModelProperty("使用者名稱")
    public String username;

    @ApiModelProperty("密碼")
    public String password;
}

controller

package com.shuang.controller;

import com.shuang.pojo.User;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

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

    //主要我們的介面中，返回值中存在實體類，他就會被掃描到Swagger中。
    @PostMapping("/user")
    public User user(){
        return new User();
    }
    //Operation介面，不是放在類上的,是方法
    @ApiOperation("Hello控制類")
    @GetMapping("/hello2")
    public String hello2(@ApiParam("使用者名稱") String username){
        return "hello"+username;

    }

    @ApiOperation("post測試類")
    @PostMapping("/postt")
    public User hello3(@ApiParam("使用者名稱") User user){
        return user;

    }
}

總結：
1，我們可以通過Swagger給一些比較難理解的屬性或者介面，增加註釋資訊。
2，介面文件實時更新。
3，可以線上測試。
Swagger是一個優秀的工具，幾乎所有大公司都有使用它。
【注意點】在正式釋出的時候，關閉Swagger！！出於安全，也節約記憶體。