SpringBoot中配置Swagger

撒子是Swagger？

• 使用swagger可以幫助我們更簡單的API接口的開發
• API文檔與API定義同步更新，可以在線測試API接口（API接口就是controller的requestmapping）

Swagger其實就是我們前後端分離時來實現前後端開發的信息及時更新Api的一個框架，是前後端的唯一聯繫。比如我們後端寫了一些controller接口，前端就能通過訪問swagger-ui來及時的查看到。

 

Swagger的頁面主要有四個部分：

• Swagger信息：開發者的一些信息什麼的。
• 接口信息：我們後端寫的controller接口的信息。
• 實體類信息：就是實體類信息啦，不過只有在controller中返回值有實體類的纔會有顯示。
• 分組：對應着一個個的Docket。

 

 

Swagger的使用

1、新建一個SpringBoot-web項目

2、導入相關依賴

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

3、配置Swagger

在SwaggerConfig中配置Swagger的基本信息：

​
package com.lyr.swagger.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;

import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;

@Configuration
@EnableSwagger2   //開啓Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean實例
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    //配置Swagger信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("lyr", "https://blog.csdn.net/wan_ide", "[email protected]");
        return new ApiInfo(
                "Lyr's Api Documentation",
                "面朝大海，然後春暖花開",
                "1.0",
                "https://blog.csdn.net/wan_ide",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

​

效果：

 

Swagger配置掃描接口

RequestHandlerSelectors 配置要掃描接口的方式：

• basePackage：指定要掃描的包
• any()：描述全部
• none()：不掃描
• withClassAnnotation：掃描類上的註解，參數是一個註解的反射對象
• withMethodAnnotation：描述方法的註解

 

package com.lyr.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;

@Configuration
@EnableSwagger2   //開啓Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean實例
    @Bean
    public Docket docket(Environment environment){

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //.enable(false)  是否啓動Swagger
                .enable(flag)
                .select()
                //RequestHandlerSelectors 配置要掃描接口的方式
                //basePackage：指定要掃描的包
                //any()：描述全部
                //none()：不掃描
                //withClassAnnotation：掃描類上的註解，參數是一個註解的反射對象
                //withMethodAnnotation：描述方法的註解
                //.apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
                .apis(RequestHandlerSelectors.basePackage("com.lyr.swagger.controller"))
                //paths() 過濾掃描路徑
                //.paths(PathSelectors.ant("/lyr/**"))
                .build();
    }
}

 

使Swagger在生產環境中使用，在發佈時不使用

1、新建一個application-dev.properties，生產環境時的配置，設置端口號爲8081

2、新建一個application-pro.properties，發佈環境時的配置，設置端口號爲8082

3、在application.properties中激活生產環境時的配置：

spring.profiles.active=pro

在SwaggerConfig中配置根據環境啓動Swagger：

package com.lyr.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;

import static springfox.documentation.service.ApiInfo.DEFAULT_CONTACT;

@Configuration
@EnableSwagger2   //開啓Swagger2
public class SwaggerConfig {
    //配置了Swagger的Docket的bean實例
    @Bean
    public Docket docket(Environment environment){
        //設置要顯示的Swagger環境
        Profiles profiles = Profiles.of("pro");
        //通過environment.acceptsProfiles判斷是否處在自己設定的環境當中
        boolean flag = environment.acceptsProfiles(profiles);


        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lyr.swagger.controller"))
                .build();
    }
}

效果：

當生產時（激活dev）可以訪問，當發佈時（激活pro）不可以訪問​​​​​​​

 

配置API文檔的分組：

.groupName("lyr")

配置多個分組就new多個Docket。

 

Swagger中的註解

• @ApiModel("用戶實體類")：給Models加上註釋，用在實體類上。但是要求返回值中存在實體類，纔會被掃描到。
• @ApiModelProperty("用戶名")：給實體類中的屬性加上註釋，用在屬性上。
• @ApiOperation("hello的控制類")：給controller中的接口加上註釋，只能放在方法上。
• @ApiParam("用戶名")：public String hello(@ApiParam("用戶名")String username){}