springboot集成swagger2

1、创建springboot项目
如何快速搭建springboot项目此处不做赘述。
2、添加swagger依赖
以maven为例：

<!-- swagger2  -->
<!-- 核心依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<!-- 界面依赖 -->
<!-- UI界面有两种，引入任意一个即可 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

<!-- bootstrap版界面-->
<!-- 引入swagger-bootstrap-ui包 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.8.5</version>
</dependency>

<!-- 或者直接引入 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.2</version>
</dependency>

三种UI的不同访问地址：
  - springfox-swagger-ui：域名 + '/swagger-ui.html' (IP+端口+'/swagger-ui.html')
  - swagger-bootstrap-ui：域名 + '/doc.html'(IP+端口+'/doc.html')
  - knife4j-spring-boot-starter：域名 + '/doc.html'(IP+端口+'/doc.html')

3、配置swagger：

@Configuration // 配置类
@EnableSwagger2 // 启动swagger2的自动配置
public class SwaggerConfig {

}

knife4j用如下注解：

@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {

}

4、启动项目，访问

• springfox-swagger-ui：localhost:8080/swagger-ui.html
  
• swagger-bootstrap-ui：localhost:8080/doc.html
  ]
• knife4j-spring-boot-starter：localhost:8080/doc.html
  
  注：

  • springboot高版本整合swagger2时项目启动失败，兼容性问题，需在配置文件添加如下配置：

    spring.mvc.pathmatch.matching-strategy=ant_path_matcher
    

  • Java11版本整合swagger2时项目启动失败，因为Java11中缺少部分依赖，需引入如下依赖：

    <dependency>
        <groupId>javax.xml.bind</groupId>
        <artifactId>jaxb-api</artifactId>
        <version>2.2.12</version>
    </dependency>
    

5、配置扫描
在未配置扫描包或者类的情况下，swagger会扫描所有controller类中的方法。
SwaggerConfig:最小配置

// 最小配置
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2) //swagger版本
            .select() // 相当于开启扫描配置
            //扫描那些controller
            .apis(RequestHandlerSelectors.basePackage("com.xiaoyu.controller")) // 配置基于包的扫描
            .build();
}

扫描可选配置：
![图片]
docket可选配置：

PS：enable选项一般会配置在环境变量中，针对不同环境配置不同的值，生产环境正常情况下会配置为false(为不可用)。
apiInfo配置：

配置示例：

@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)//swagger版本
            .apiInfo(apiInfo())
            .enable(true)
            .groupName("测试")
            .pathMapping("/")
            .securitySchemes(securitySchemes())
            .select()
            //扫描那些controller
            .apis(RequestHandlerSelectors.basePackage("com.xiaoyu.controller"))
            .build();
}

/**
* 主页说明
*/
public ApiInfo apiInfo() {
    ApiInfo apiInfo =  new ApiInfoBuilder()
            .description("我爱swagger")
            .title("我爱学习")
            .contact(new Contact("周小瑜", "", "zhouxiaoyu****@163.com"))
            .version("1.0.0")
            .license("swagger")
            .licenseUrl("")
            .build();
    return apiInfo;
}

/**
 * 添加 自定义参数  支持多个
 * 默认全面访问路径需要添加次参数，新增配置可以匹配哪些路径支持
 */
private List<ApiKey> securitySchemes() {
    List<ApiKey> apiKeyList= new ArrayList();
    apiKeyList.add(new ApiKey("x-auth-token", "token", "header"));
    return apiKeyList;
}
配置多个docket
@Bean
public Docket docket() {
    return new Docket(DocumentationType.SWAGGER_2)//swagger版本
            .apiInfo(apiInfo())
            .enable(true)
            .groupName("测试")
            .pathMapping("/")
            .securitySchemes(securitySchemes())
            .select()
            //扫描那些controller
            .apis(RequestHandlerSelectors.basePackage("com.xiaoyu.controller.test"))
            .build();
}

@Bean
public Docket docket2() {
    return new Docket(DocumentationType.SWAGGER_2)//swagger版本
            .apiInfo(apiInfo())
            .enable(true)
            .groupName("用户模块")
            .pathMapping("/")
            .securitySchemes(securitySchemes())
            .select()
            //扫描那些controller
            .apis(RequestHandlerSelectors.basePackage("com.xiaoyu.controller.user"))
            .build();
}

@Bean
public Docket docket3() {
    return new Docket(DocumentationType.SWAGGER_2)//swagger版本
            .apiInfo(apiInfo())
            .enable(true)
            .groupName("订单模块")
            .pathMapping("/")
            .securitySchemes(securitySchemes())
            .select()
            //扫描那些controller
            .apis(RequestHandlerSelectors.basePackage("com.xiaoyu.controller.order"))
            .build();
}

springboot集成swagger2及配置至此完成。

常用注解用法可参照：👉swagger2常用注解详解