springboot项目整合swagger2

springboot项目整合swagger2

插件介绍

swagger作为一款2w多stars的文档说明工具(点击查看)，和postman一样深受广大开发者喜好，不仅仅能独立部署展示，也可以集成到开发框架中，支持多种开发语言，java、php都有相应的开源插件使用。本篇文章中主要介绍JAVA中使用swagger功能。

java中使用，其插件仓库查看：https://mvnrepository.com/artifact/io.springfox，可以看到有许多springfox模块，那什么是springfox？其前身为swagger-springmvc，是一款开源的API doc框架，可以将我们的请求方法以文档方式呈现，后面改为SpringFox(官网)，并扩展了一些功能模块，但是貌似好久没有更新了，最新更新的时间还是2020年。

主要模块说明：

模块	描述
SpringFox Swagger2	swagger2核心功能，不带界面
SpringFox Swagger UI	swagger2展示UI，自动获取JSON数据，并展示
SpringFox Boot Starter	集成启动swagger2服务，这时候无需在配置文件中添加@EnableSwagger2
SpringFox Bean Validators	验证功能，可以对请求参数进行校验
SpringFox Core	SpringFox核心包，封装了一些常用实例
SpringFox Spring Web	SpringFox针对Spring Web的核心操作，初始化也在此模块中
SpringFox SPI	SpringFox一系列Plugin接口声明
SpringFox Swagger Common	SpringFox 常见功能，Plugin功能的实现
SpringFox Spring WebMVC	SpringFox针对Spring WebMVC的核心操作
SpringFox Schema	常见方法实现类

其它还有一些不常见的模块不一一介绍了，有需要的可以去官网查看。

快速安装

安装swagger插件还是比较简单，主要分为以下步骤：

• 在pom.xml文件中添加对应依赖：

<dependency>
   <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-bean-validators</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

• 配置Swagger启动：

@Configuration
//@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier, ServletEndpointsSupplier servletEndpointsSupplier, ControllerEndpointsSupplier controllerEndpointsSupplier, EndpointMediaTypes endpointMediaTypes, CorsEndpointProperties corsProperties, WebEndpointProperties webEndpointProperties, Environment environment) {
        List<ExposableEndpoint<?>> allEndpoints = new ArrayList();
        Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
        allEndpoints.addAll(webEndpoints);
        allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
        allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());
        String basePath = webEndpointProperties.getBasePath();
        EndpointMapping endpointMapping = new EndpointMapping(basePath);
        boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);
        return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(), new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping, null);
    }

    private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) {
        return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));
    }
}

由于使用了springfox-boot-starter，所以可以省略@EnableSwagger2标签，也可以去除此依赖，打开@EnableSwagger2标签。

新版本springboot整合会有问题，问题解决方案请参考我写的另外一篇文章，《springboot及swagger整合报错：documentationPluginsBootstrapper》。

• 启动应用访问

正常启动不报错，访问http://localhost:8088/swagger-ui/，能够看到如下界面：

至此，swagger2整合完毕，接下来，再详细学习一下针对swagger2的详细配置及高级使用技巧。