Spring 4.2.2 以上版本和 swagger 集成方案和踩过的坑

本贴最后更新于 668 天前,其中的信息可能已经时过境迁

因为公司使用的 Spring 版本太高,在集成 swagger 的时候会存在一些问题,而网上的很多实例大多都是版本比较低的,为了使朋友们少踩坑,我这边将集成的过程记录一下。

  1. 引入 Spring、swagger 的相关 jar 包(springfox-swagger2、springfox-swagger-ui),在 pom.xml 中配置:
<dependency>  
            <groupId>io.springfox</groupId>  
            <artifactId>springfox-swagger2</artifactId>  
            <version>2.4.0</version>  
            <exclusions>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-core</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-beans</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-context</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-context-support</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-aop</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-tx</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-orm</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-jdbc</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-web</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-webmvc</artifactId>  
                </exclusion>  
                <exclusion>  
                    <groupId>org.springframework</groupId>  
                    <artifactId>spring-oxm</artifactId>  
                </exclusion>  
            </exclusions>  
        </dependency>  
        <dependency>  
            <groupId>io.springfox</groupId>  
            <artifactId>springfox-swagger-ui</artifactId>  
            <version>2.4.0</version>  
        </dependency> 

提醒: 特别注意,springfox-swagger2 在集成的时候,已经引入了 Spring 的相关 jar,特别是 spring-context、spring-context-support 的版本和项目中使用的版本完全不一致,项目在启动的时候出现很多包冲突的问题,这边在引入 pom.xml 文件的时候过滤掉了 Spring 的相关 jar 包。

  1. 编写 Swagger 的配置类:
package com.ml.honghu.swagger.web;  
  
import org.springframework.context.annotation.Bean;  
import org.springframework.context.annotation.ComponentScan;  
import org.springframework.context.annotation.Configuration;  
import org.springframework.web.servlet.config.annotation.EnableWebMvc;  
  
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;  
  
@EnableWebMvc  
@EnableSwagger2  
@Configuration  
@ComponentScan(basePackages ={"com.ml.honghu.**.rest"})  
public class SwaggerConfig {  
    @Bean  
    public Docket createRestApi() {  
        return new Docket(DocumentationType.SWAGGER_2)  
                .apiInfo(apiInfo())  
                .select()  
                .apis(RequestHandlerSelectors.basePackage("com.ml.honghu"))  
                .paths(PathSelectors.any())  
                .build();  
    }  
  
    private ApiInfo apiInfo() {  
        return new ApiInfoBuilder()  
                .title("接口列表 v1.0")  
                .description("接口信息")  
                .termsOfServiceUrl("http://honghu.com")  
                .contact(new Contact("", "", "HongHu"))  
                .version("1.1.0")  
                .build();  
    }  
}  

3 在 spring-mvc.xml 文件中进行过滤器的配置,过滤掉 swagger 的相关访问配置:

<mvc:exclude-mapping path="/swagger*/**"/>  
<mvc:exclude-mapping path="/v2/**"/>  
<mvc:exclude-mapping path="/webjars/**"/> 

4 服务配置项

@Api("区域服务")
@RestController  
@RequestMapping(value = "/rest/area")  
public class AreaService  {  
  
    @Autowired  
    private AreaService areaService;  
      
    <span style="color: #ff0000;">@ApiOperation(value = "区域列表", httpMethod = "GET", notes = "区域列表")</span>  
    @IsLogin  
    @ResponseBody  
    @RequestMapping(value = "treeData", method = RequestMethod.GET)  
    public List<Map<String, Object>> treeData(  
            <span style="color: #ff0000;">@ApiParam(required = true, value = "区域ID")</span>  @RequestParam(required=false) String extId, HttpServletResponse response) {  
        List<Map<String, Object>> mapList = Lists.newArrayList();  
        List<Area> list = areaService.findAll();  
        for (int i=0; i<list.size(); i++){  
            Area e = list.get(i);  
            if (StringUtils.isBlank(extId) || (extId!=null && !extId.equals(e.getId()) && e.getParentIds().indexOf(","+extId+",")==-1)){  
                Map<String, Object> map = Maps.newHashMap();  
                map.put("id", e.getId());  
                map.put("pId", e.getParentId());  
                map.put("name", e.getName());  
                mapList.add(map);  
            }  
        }  
        return mapList;  
    }  
}  

  • Spring

    Spring 是一个开源框架,是于 2003 年兴起的一个轻量级的 Java 开发框架,由 Rod Johnson 在其著作《Expert One-On-One J2EE Development and Design》中阐述的部分理念和原型衍生而来。它是为了解决企业应用开发的复杂性而创建的。框架的主要优势之一就是其分层架构,分层架构允许使用者选择使用哪一个组件,同时为 JavaEE 应用程序开发提供集成的框架。

    811 引用 • 1390 回帖 • 681 关注
  • Swagger

    Swagger 是一款非常流行的 API 开发工具,它遵循 OpenAPI Specification(这是一种通用的、和编程语言无关的 API 描述规范)。Swagger 贯穿整个 API 生命周期,如 API 的设计、编写文档、测试和部署。

    22 引用 • 35 回帖 • 3 关注
  • 一些有用的避坑指南。

    62 引用 • 87 回帖

赞助商 我要投放

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...