springboot集成swagger

一.swagger概述

swagger是一个用于设计、构建和文档化 RESTful API 的开源框架。它提供了一组工具，使得开发人员能够更轻松地定义、描述和测试API接口，它主要包括四大组件。

 Swagger规范: 定义了一种格式化的API规范，使用YAML或JSON格式，用于描述API的各种细节，包括路由、参数、返回值等。

 

- Swagger编辑器: 提供了一个交互式的编辑界面，让开发人员能够方便地编写和验证Swagger规范文件。

 

- Swagger UI: 一个动态生成的HTML文件，可以将Swagger规范文件渲染成一个美观易用的API文档网页。通过Swagger UI，开发人员可以直观地查看API接口的详细信息，包括请求示例、响应模型和参数说明。

 

- Swagger Codegen: 一个自动生成API客户端代码的工具，根据Swagger规范文件，它可以生成多种编程语言的代码框架，帮助开发人员快速集成和调用API接口。

二，使用swagger

1.首先导入依赖

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

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

2.添加配置类，

@Configuration
@EnableSwagger2 //标记项目启用 Swagger API 接口文档
public class SwaggerConfig
{

    /** 是否开启swagger */
//    @Value("${swagger.enabled}")
    private boolean enabled = true;

    /** 设置请求的统一前缀 */
//    @Value("${swagger.pathMapping}")
//    private String pathMapping;

    /**
     * 创建API
     */
    @Bean
    public Docket createRestApi()
    {   // 创建Docket对象
        return new Docket(DocumentationType.SWAGGER_2) // 文档类型，使用Swagger2
                // 是否启用Swagger
                .enable(enabled)
                // 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
                // 设置Api信息
                .apiInfo(apiInfo())
                // 设置哪些接口暴露给Swagger展示
                .select()
                // 扫描所有有注解的api，用这种方式更灵活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 扫描指定包中的swagger注解
                // .apis(RequestHandlerSelectors.basePackage("com.project.tool.swagger"))
                // 扫描所有
                .paths(PathSelectors.any())
                // 构建出 Docket 对象
                .build()
                /* 设置安全模式，swagger可以设置访问token */
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
//                .pathMapping(pathMapping);
    }

    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<SecurityScheme> securitySchemes()
    {
        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
        apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
        return apiKeyList;
    }

    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts()
    {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .forPaths(PathSelectors.regex("^(?!auth).*$"))
                        .build());
        return securityContexts;
    }

    /**
     * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth()
    {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    /**
     * 添加摘要信息
     */
    private ApiInfo apiInfo()
    {
        // 用ApiInfoBuilder进行定制
        return new ApiInfoBuilder()
                // 设置标题
                .title("标题：Swagger测试_接口文档")
                // 描述
                .description("描述：用于管理人员信息,具体包括XXX,XXX模块...")
                // 作者信息
                .contact(new Contact("fyt", null, null))
                // 版本
                .version("版本号:1.0" )
                .build();
    }
}

3.编写controller

 4.启动项目。然后浏览器访问 http://127.0.0.1:4000/swagger-ui.html (`4000是你项目端口`)地址，就可以看到 Swagger 生成的 API 接口文档。如下：

 

 为什么文档中有这么多条接口信息，因为swagger是基于RESTful 风格的框架， 但controller中映射路径使用的是@RequestMapper注解，表示可以接收所有请求，所以swagger把每个请求方式都展示出来了。

5.报错

如果出现报错信息

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

表示springboot版本和swagger版本不符合。一般swagger2只支持springboot2.5以下的版本，但我们通常不改变springboot版本，所以可以在application.yml中添加以下配置：

spring:

  mvc:

    pathmatch:

      matching-strategy: ant_path_matcher