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/", "3342239623@qq.com");

        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，也節省運行內存