Swagger简介

Swagger是当前最好用的Restful API文档生成的开源项目，实现了与SpingMVC框架的无缝集成功能，方便生成spring restful风格的接口文档，同时swagger-ui还可以测试spring restful风格的接口功能。

本文档只介绍项目中使用spring 3.2.10版本集成和注意事项（遇到了一些坑）。

SpringBoot项目(4.0以上版本)与swagger2集成相对比较简单，可以自己百度搜索。

项目环境介绍

· JDK 1.8

· Spring 3.2.10

· swagger-springmvc 1.0.2

集成swagger步骤

第一步 引入jar包

<!-- swagger start -->

<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>

     <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>

<!-- swagger end -->

由于项目中已经集成过jackson的jar包 （参考文档链接）根据具体情况添加

<dependency>

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

        <artifactId>jackson-annotations</artifactId>

        <version>2.4.4</version>

    </dependency>

    <dependency>

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

        <artifactId>jackson-databind</artifactId>

        <version>2.4.4</version>

    </dependency>

    <dependency>

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

        <artifactId>jackson-core</artifactId>

        <version>2.4.4</version>

第二部 swaggerconfig配置类

新建了一个包名

Swagger的配置实际上就是自定义一个Config类，通过java编码的方式实现配置

package com.zxq.iov.cloud.sp.as.web.config;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.context.annotation.Bean;

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;

import com.mangofactory.swagger.models.dto.ApiInfo;

import com.mangofactory.swagger.plugin.EnableSwagger;

import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

/**

 *

 * @author Administrator

 * /sp-as-web/src/main/java/com/zxq/iov/cloud/sp/as/web/config/SwaggerConfig.java

 */

@EnableSwagger

public class SwaggerConfig {

private SpringSwaggerConfig springSwaggerConfig;  

    /**

     * Required to autowire 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(this.springSwaggerConfig)  

                .apiInfo(apiInfo())  

                .includePatterns(".*?");  

    }  

    private ApiInfo apiInfo(){  

        ApiInfo apiInfo = new ApiInfo(  

                "springmvc  swagger",  

                "spring-API swagger",  

                "My Apps API terms of service",  

                "",  

                "web app",  

                "My Apps API License URL");  

        return apiInfo;  

    }  

}

第三步 在spring-mvc.xml中配置bean

维保模块项目是zxq-servlet.xml

<!-- swagger start  -->

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

       <bean class="com.zxq.iov.cloud.sp.as.web.config.SwaggerConfig" /> 

<!— swagger-ui文件的的过滤 -->   

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

<!-- swagger end -->

第四步 Swagger-UI配置

Swagger扫描解析得到的是一个json文档，对于用户不太友好。下面介绍swagger-ui，它能够友好的展示解析得到的接口说明内

首先去Swagger-UI官网git下载版本2.10的，别下载3.0以上的，否则就出现坑爹的现象，你的页面始终是No operations defined in spec!， 
像这样，急死人 

1）Swagger-UI的git地址：https://github.com/swagger-api/swagger-ui/tree/v2.2.10 
下载这里面的dist文件夹，把文件夹整个拷贝到你项目工程的webapp下 
2）找到dist文件夹下的index.html文件，把大概第40行的url改成url = “http://localhost:8080/项目名称/api-docs”;注意这个api-docs是固定的，不要改！ 

 获取其所有的 dist 目录下东西放到需要集成的项目里，本文放入 src/main/webapp /swagger/ 目录下。  

修改swagger/index.html文件，默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON，这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式，{}中的值根据自身情况填写。

比如我的url值为：http://localhost:8083/sp-as/api-docs

第五步 web.xml的修改

统一登录过滤的设置

<filter>

<filter-name>casAuthenticationFilter</filter-name>

<filter-class>org.jasig.cas.client.authentication.AuthenticationFilter</filter-class>

<init-param>

        <param-name>ignorePattern</param-name>

         <param-value>/swagger/*|/api-docs/*</param-value>

     </init-param>

</filter>

<filter-mapping>

<filter-name>casAuthenticationFilter</filter-name>

<url-pattern>*.html</url-pattern>

</filter-mapping>

参考文档链接

https://www.oschina.net/question/2548090_2160781

https://blog.csdn.net/gyb_csdn/article/details/75123575

本文作者:薛沉沉