springboot项目整合swagger2

ゞ浴缸里的玫瑰 2024-05-25 17:36 64阅读 0赞

## springboot项目整合swagger2 ##

### 插件介绍 ###

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

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

主要模块说明：

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

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

### 快速安装 ###

安装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》][springboot_swagger_documentationPluginsBootstrapper]。

*  启动应用访问

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

![在这里插入图片描述][edb04673ef5e47f7b4cdb132f2d58c13.jpeg_pic_center]  
至此，swagger2整合完毕，接下来，再详细学习一下针对swagger2的详细配置及高级使用技巧。

[Link 1]: https://swagger.io/
[https_mvnrepository.com_artifact_io.springfox]: https://mvnrepository.com/artifact/io.springfox
[Link 2]: http://springfox.github.io/springfox/
[Link 3]: https://springfox.github.io/springfox/
[springboot_swagger_documentationPluginsBootstrapper]: https://blog.csdn.net/hunkxia/article/details/127404964
[http_localhost_8088_swagger-ui]: http://localhost:8088/swagger-ui/
[edb04673ef5e47f7b4cdb132f2d58c13.jpeg_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/25/9cf74645edf2439890b117e7f35b539b.jpeg