springMvc集成swagger

 

一、环境

Spring4.1.6+maven3.1+swagger1.0.2+swagger-ui2.2.10

注意：swagger-springmvc这个包，2015年后就没有更新了。所以只要是用springmvc这个包，swagger-ui的版本不可太高，亲测2.3.0版本不可用。

二、swagger-ui下载地址

https://github.com/swagger-api/swagger-ui

网页最下端有各个版本信息，选择对应的版本下载

三、跟ssm框架集成

注意：自己搭建一个ssm框架的maven项目，在此不做过多的赘述。

1.加入swagger和springMVC maven依赖

<!-- swagger-springmvc -->

    <dependency>

        <groupId>com.mangofactory</groupId>

        <artifactId>swagger-springmvc</artifactId>

        <version>1.0.2</version>

    </dependency>

    <dependency>

        <groupId>com.mangofactory</groupId>

        <artifactId>swagger-models</artifactId>

        <version>1.0.2</version>

    </dependency>

    <dependency>

    <groupId>com.wordnik</groupId>

    <artifactId>swagger-annotations</artifactId>

    <version>1.3.11</version>

</dependency>

    <!-- swagger-springmvc dependencies -->

    <dependency>

        <groupId>com.google.guava</groupId>

        <artifactId>guava</artifactId>

        <version>15.0</version>

    </dependency>

    <dependency>

        <groupId>com.fasterxml</groupId>

        <artifactId>classmate</artifactId>

        <version>1.1.0</version>

    </dependency>

 +++++++++++++++++++++++++++分割线+++++++++++++++++++++++++++++++++++++

如有需要，可自行添加Json相关的包

<dependency>  

            <groupId>com.fasterxml.jackson.core</groupId>  

            <artifactId>jackson-core</artifactId>  

            <version>2.1.0</version>  

        </dependency>  

        <dependency>  

            <groupId>com.fasterxml.jackson.core</groupId>  

            <artifactId>jackson-databind</artifactId>  

            <version>2.1.0</version>  

        </dependency>

        <dependency>  

            <groupId>com.fasterxml.jackson.core</groupId>  

            <artifactId>jackson-annotations</artifactId>  

            <version>2.1.0</version>  

        </dependency>

        <dependency>

    <groupId>com.fasterxml.jackson.dataformat</groupId>

    <artifactId>jackson-dataformat-xml</artifactId>

    <version>2.1.0</version>

</dependency>

2.创建自定义swagger初始化配置文件：

           Java文件会单独上传，此处放的是截图

3. 将swagger配置类及依赖SpringSwaggerConfig加载到spring容器中

<!-- swagger注解 -->

<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />

<bean class="SwaggerConfig.java文件的路径" />   

4.配置相关controller的api

说明：其中@ApiOperation和@ApiParam为添加的API相关注解，个参数说明如下：

@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；

@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

5.集成Swagger UI

在GitHub上将swaggerui下载，地址:https://github.com/swagger-api/swagger-ui

解压后将dist文件夹中所有的文件拷贝到web-inf/swagger这里的swagger是自定义的你可以写为自己创建的目录。

修改index.html中的 http://petstore.swagger.wordnik.com/v2/swagger.json修改为自己项目路径+api-docs,例如：

http://localhost:8080/项目名/api-docs

6.在spring-mvc.xml中过滤掉swagger-ui的文件：

<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

按照第5步定义的路径写

到这里基本完成了springmvc和swagger的整合。

7.测试

访问自己的项目直接进入swagger下的index页面，即可看到各个接口

访问路径http://localhost:8080/项目名称/swagger/index.html

使用：找到需要调用的接口，输入参数，点击 try it out 发送请求即可

接口响应结果

四、过程中出现的问题

1.版本不对出现的问题

 完整的SwaggerConfig

@Configuration
@EnableSwagger
@EnableWebMvc
@ComponentScan(basePackages="com.dljs.swagger") 
public class SwaggerConfig {
	
	private SpringSwaggerConfig springSwaggerConfig;
	
	@Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
    {
        this.springSwaggerConfig = springSwaggerConfig;
    }
	
	/**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation()
    {
        return new SwaggerSpringMvcPlugin(springSwaggerConfig).
        		apiInfo(apiInfo()).
        		includePatterns(".*?");
    }
    
    private ApiInfo apiInfo()
    {
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title",
                "My Apps API Description",
                "My Apps API terms of service",
                "My Apps API Contact Email",
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }

}