在Springboot项目中集成swagger2

注意：开始之前，请先确保自己的Springboot项目能跑起来。

第一步，往pom文件中添加swagger2需要的依赖

        
        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        

注意：Swagger2的版本与自己的Springboot版本需要匹配，不要跨大版本，跨大版本兼容问题会相当多。博主这里的Springboot使用的是2.x的版本，Swagger2也是2.x的版本。

如何知晓自己的Swagger2与Springboot版本是否匹配呢？

引入Swagger2的依赖后再次启动一下自己的Springboot项目，如果不报错，那么就没有问题

如果报错，那么就调整版本

第二步、根据自己的需求编写Swagger的配置类

新建一个SwaggerConfig类，

(1)单包扫描：

只扫描一个包下的所有接口，具体代码如下

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 创建API应用(注入Docket)
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("admin")
                .apiInfo(apiInfo("Admin APIs", "1.0"))
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
          // 扫描指定包中的swagger注解
.apis(RequestHandlerSelectors.basePackage("com.rainng.coursesystem.controller.admin"))
                .paths(PathSelectors.any())//选择访问路径的规则，为所有访问路径
                .build();
    }


    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://ip:port/swagger-ui.html
     *
     * @return
     */
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfoBuilder()
                .title(title)
                .description("更多请关注: https://blog.csdn.net/qq_53679622")//描述
                .termsOfServiceUrl("https://blog.csdn.net/qq_53679622")//作者的社交网址
                .contact(new Contact("huangtuyou", "https://blog.csdn.net/qq_53679622", "[email protected]"))//作者的联系方式:姓名、网址、邮箱
                .version(version)
                .build();
    }

}

注意：这种方式的配置，这个被扫描的包里面只能有接口，而不能存在其他的包，不然swagger找不到接口

(2)多包扫描：

需要扫描多个包下的接口

<1>多包扫描，但是不需要分模块

在单包扫描的基础上，改一下API的扫描规则就行了，把扫描指定包下的接口，改成扫描带指定注解的接口

将

.apis(RequestHandlerSelectors.basePackage("com.rainng.coursesystem.controller.admin"))

改成

.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))

具体代码如下

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 创建API应用(注入Docket)
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 多包扫描，但是不用分模块，扫描带有指定注解的api，建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("admin")
                .apiInfo(apiInfo("Admin APIs", "1.0"))
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
                // 扫描所有有注解的api，用这种方式更灵活,但是不能分模块，依然有局限性
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://ip:port/swagger-ui.html
     *
     * @return
     */
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfoBuilder()
                .title(title)
                .description("更多请关注: https://blog.csdn.net/qq_53679622")//描述
                .termsOfServiceUrl("https://blog.csdn.net/qq_53679622")//作者的社交网址
                .contact(new Contact("huangtuyou", "https://blog.csdn.net/qq_53679622", "[email protected]"))//作者的联系方式
                .version(version)
                .build();
    }

}

这种方式的配置，会扫描全部带有指定注解的api，用这种方式更灵活一点,但是不能分模块，依然有局限性。

<2>多包扫描，需要分模块

在单包扫描配置的基础上，往Docket里面多注入几个模块对应的bean就可以了

具体代码如下

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.ApiInfoBuilder;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 创建API应用(注入Docket)
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 多包扫描，分模块建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket restApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("admin")
                .apiInfo(apiInfo("Admin APIs", "1.0"))
                .useDefaultResponseMessages(true)
                .forCodeGeneration(false)
                .select()
                // 扫描指定包中的swagger注解
                .apis(RequestHandlerSelectors.basePackage("com.rainng.coursesystem.controller.admin"))
                .paths(PathSelectors.any())
                .build();
    }

    //第二个bean，用来展示学生模块的测试接口
    @Bean
    public Docket restApi2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("student")
                .apiInfo(apiInfo("Student APIs", "1.0"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rainng.coursesystem.controller.student"))
                .paths(PathSelectors.regex("/student.*"))
                .build();
    }

    //第三个bean，用来展示老师模块的测试接口
    @Bean
    public Docket restApi3() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("teacher")
                .apiInfo(apiInfo("Teacher APIs", "1.0"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rainng.coursesystem.controller.teacher"))
                .paths(PathSelectors.regex("/teacher.*"))
                .build();
    }
    //第四个bean，用来展示用户模块的测试接口
    @Bean
    public Docket restApi4() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("user")
                .apiInfo(apiInfo("user APIs", "1.0"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rainng.coursesystem.controller.user"))
                .paths(PathSelectors.any())
                .build();
    }
    //第五个bean，用来展示操作模块的测试接口
    @Bean
    public Docket restApi5() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("option")
                .apiInfo(apiInfo("option APIs", "1.0"))
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.rainng.coursesystem.controller.option"))
                .paths(PathSelectors.any())
                .build();
    }


    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://ip:port/swagger-ui.html
     *
     * @return
     */
    private ApiInfo apiInfo(String title, String version) {
        return new ApiInfoBuilder()
                .title(title)
                .description("更多请关注: https://blog.csdn.net/qq_53679622")//描述
                .termsOfServiceUrl("https://blog.csdn.net/qq_53679622")//作者的社交网址
                .contact(new Contact("huangtuyou", "https://blog.csdn.net/qq_53679622", "[email protected]"))//作者的联系方式
                .version(version)
                .build();
    }

}

优点：这种方式建立的接口文档看起来非常清晰，结构层次很分明，使用起来更方便。

配置好后，启动自己的项目，在浏览器输入访问地址http://ip:port/swagger-ui.html

即可出现swaggerUI的界面，例如：http://localhost:8085/swagger-ui.html

 

 出现这样的界面说明我们的swagger2就已经配置好了

第三步、美化Swagger2的界面

配置好swagger2后，我们发现界面风格稍微显得单调了一点，可以使用bootstrap-ui对其进行美化

引入依赖即可

        
            com.github.xiaoymin
            swagger-bootstrap-ui
            1.9.6
        

美化后的界面访问路径为http://ip:port/doc.html

重新启动自己的项目,输入访问地址，即可出现bootstrap-ui的界面

例如：http://localhost:8085/doc.html

 

 

四、博主踩过的一些坑

1、引入swagger2的依赖，还没有写任何配置，启动项目后疯狂报错

原因：我刚开始建了一个3.x版本的Springboot项目，引入了某个2.x版本的swagger依赖，版本不兼容

解决办法：调整版本，把Springboot的版本换成2.x的版本

2、引入依赖后，修改依赖的版本，点击刷新按钮，依然不起作用

原因：idea的缓存没清除，即使点击了刷新按钮，实际上使用的还是原来的配置

解决办法：注释掉pom文件的依赖，让配置发生较大变化，再引入依赖，最后点击刷新按钮

3、在idea中修改swagger2的配置类后，新的配置不生效

原因：idea的缓存没清除，使用的是原来的配置数据

解决办法：在Springboot项目入口Application类上ctrl+shft+F10,这是清除缓存后重启项目。

之后刷新浏览器的访问页面就可以看到新配置对应的界面了。