swagger集成springboot，（一篇讓你瞬間精通swagger2.9.2的文章）

一，導入相關依賴

　　maven下載：springfox.swagger2，springfox.swaggerUI

　　或者在springboot項目中，直接導入一個依賴springfox-boot-starter（目前最新版本3.0.0）

        <!--swagger-->
        <!-- 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>

注意：這里我用到時swagger2.9.2版本，建議使用swagger3.0.0的

　　　swagger3.0.0是當前最新版本，它簡化了swagger2.9.2的部分操作，如號稱“零配置”，那么問題來了，博主為什么沒有直接學swagger3呢？

　　　　因為swagger3目前還是有一些不足的，且博主能力有限，不能夠直接看源碼就能學懂，所以我選擇學swagger2（網上教學ziyuanduo），

　　　　還有一個就是swagger2和3其實也沒差多少，博主打算swagger3更穩定的時候在看一遍就行了hhhhh

 

二，配值swagger，（編寫配置類）

1.集成springboot（沒有自定義，那么都走默認的）

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

}

 

2.測試：請求http://localhost:8080/swagger-ui.html

 

 

 

 

 

2.配置swagger的docket的bean實例對象docket（核心時文檔插件）

2.1，docket的bean實例來源核心

 

 

 

2.2Swagger的接口初始化配置

　　Docket.apiInfo()

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

    //配置Swagger的Docket的bean實例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){

        //存放作者信息
        Contact contact = new Contact("king", "https://www.cnblogs.com/CL-King/", "[e-mail]");

        return new ApiInfo(
                "king的Swagger API文檔",
                "測試！測試！",
                "1.0",
                "https://www.cnblogs.com/CL-King/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

}

 

2.3，Swagger配置掃描接口

　　Docket.select()

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                //requestHandlerSelector配置要掃描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.king.swagger.controller"))//basePackage基於某個包去掃描
                .build();
    }

2.4,過濾什么路徑

　　Docket.paths()

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)//paths()過濾什么路徑,只掃描自定義路徑的接口
                .paths(PathSelectors.ant("/user/**"))
                .build();
    }

 

2.5，自動啟動swagger

　　Docket.enable(),默認時true

2.6，Swagger的常用完整配置

　　補充：分組，Docket.groupName("name")

　　實現多個分組：注冊多個bean就可以了

 

 

Swagger的常用完整配置

    //配置Swagger的Docket的bean實例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(false)//enab是否啟動Swagger，默認true
                .select()
                //requestHandlerSelector配置要掃描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.king.swagger.controller"))//basePackage基於某個包去掃描
                //paths()過濾什么路徑,只掃描自定義路徑的接口
                /*.paths(PathSelectors.ant("/user/**"))*/
                .build();
    }

 

問題：如何讓swagger在開發環境中啟用，在上線環境下關閉？

思路：多環境配置，（一個開發環境dev，一個發布環境pro），

　　　通過判斷所處環境，給Docket.enable()賦值；

擴展：因為enable要的時boolean值，

　　　方法一：所以可以才環境配置文件中寫死，在swagger配置類中獲取最后傳給Docket.enable（）

　　　方法二：也可以通過子swagger類中寫死開啟swagger的環境的方式來實現

　　　實現寫的是方法二的代碼，方法一簡單就不去寫了

實現：

    //配置Swagger的Docket的bean實例
    @Bean
    public Docket docket(Environment environment){

        //設置要開啟swagger的環境
        Profiles profiles = Profiles.of("dev", "test");

        //通過environment.acceptsProfiles（）方法判斷是否處於設定環境
        boolean b = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(b)//enab是否啟動Swagger，默認true
                .select()
                //requestHandlerSelector配置要掃描接口的方式
                .apis(RequestHandlerSelectors.basePackage("com.king.swagger.controller"))//basePackage基於某個包去掃描
                //paths()過濾什么路徑,只掃描自定義路徑的接口
                /*.paths(PathSelectors.ant("/user/**"))*/
                .build();
    }

 

3，實體類配置（待更）

問題：swagger如何與實體類建立關聯

解答：在controller層，放回的值只要包含實體類，swagger就會檢測到該實體類

    //只要接口的返回值中存在實體類，該實體類就會被swagger掃描到
    @GetMapping(value = "/user")
    public User user(){

        return new User();
    }

 

swagger關於實體類的注解：

@ApiModel：給實體類加注釋通過Swagger，作用在類上

@ApiModelProperty：給實體類的字段加注釋通過Swagger，作用在字段上

//給實體類加注釋通過Swagger，作用在類上
@ApiModel("用戶實體類")
public class User {

    //給實體類的字段加注釋通過Swagger，作用在字段上
    @ApiModelProperty("用戶名")
    public String username;
    @ApiModelProperty("密碼")
    public String password;

}

 

 

 

 

 問題：細心的同學會發現，我的實體類demo的字段屬性是public當改成private后，swagger就檢測不到了，怎么辦？

解答：很簡單，通過相對應的get方式就可以啦，有這個問題的建議去看javase基礎，這是類字段屬性訪問權限問題，這里寫public是為了方便測試

 

swagger關於controller層的注解：

@ApiOperation（”xx“）作用子在方法上

@ApiParam("xx")作用方法傳參位置

    //@ApiOperation作用子在方法上
    @ApiOperation("Hello控制類")
    @GetMapping(value = "/hello2")
    public String hello2(@ApiParam("用戶名") String username){

        return "hello"+username;
    }

擴展：接口測試

1.找到要測試接口（請求），點擊try it out

 

 

輸入測試參數后，點擊Execute

 

 

 

swagger優點：

　　1.通過swagger給項目中難理解的屬性和接口加注解，方便接口測試的可讀性，提高效率

　　2.接口文檔實時更新

　　3.可以在線測試

Swagger是一個非常優秀的框架，幾乎所有成規模的公司都會使用它

注意：為確保項目安全，s項目正式發布是要關閉swagger，也節省運行內存