SpringMvc集成Swagger，搬砖搬来的心得

1.下载Swagger UI

https://github.com/swagger-api/swagger-ui/tree/master/dist

我们需要的是dist中的部分，将/dist下所有的文件复制到项目中。

2.引入jar包（jar包可能会有无用的）

<!--Swagger start-->   
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>
        
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-core</artifactId>  
            <version>2.8.0</version>  
        </dependency>  
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-databind</artifactId>  
            <version>2.6.3</version>  
        </dependency>  
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-annotations</artifactId>  
            <version>2.6.3</version>  
        </dependency>
<!--swagger end-->        

3.新增SwaggerConfig.java配置文件

   
import java.util.ArrayList;
import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import org.springframework.web.util.UriComponentsBuilder;

import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.paths.AbstractPathProvider;
import springfox.documentation.spring.web.paths.Paths;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket createAPI() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .forCodeGeneration(true)
                //重定义接口路径
                .pathProvider(new CustRelativePathProvider()) 
                .select()
                //限制读取包
                .apis(RequestHandlerSelectors.basePackage("com.cqjgsoft.base.controller"))
//                过滤生成链接
                .paths(PathSelectors.any())
                .build()
                //为每个方法添加token
                .globalOperationParameters(setHeaderToken())
                //项目上下文，如果设置错误会导致url如法访问
                .pathMapping("/ql")
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("cqjg", "http://www.jgzxsoft.com/", "1075136624@qq.com");
        return new ApiInfo("API接口",//大标题 title
                "Swagger",//小标题
                "0.0.1",//版本
                "http://www.jgzxsoft.com/",//termsOfServiceUrl
                contact,//作者
                "Blog",//链接显示文字
                "http://www.jgzxsoft.com/"//网站链接
        );
    }
    
            public class CustRelativePathProvider extends AbstractPathProvider {
                public static final String ROOT = "/";
         
                @Override
                public String getOperationPath(String operationPath) {
                    UriComponentsBuilder uriComponentsBuilder = UriComponentsBuilder.fromPath("/");
                    String uri = Paths.removeAdjacentForwardSlashes(uriComponentsBuilder.path(operationPath).build().toString());
                    return uri + ".do";
                }
         
                @Override
                protected String applicationPath() {
                    return ROOT;
                }
         
                @Override
                protected String getDocumentationPath() {
                    return ROOT;
                }
           
        }
            /**
             * 设置请求头
             * @return
             */
            private List<Parameter> setHeaderToken() {
                ParameterBuilder tokenPar = new ParameterBuilder();
                List<Parameter> pars = new ArrayList<>();
                tokenPar.name("X-Auth-Token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
                pars.add(tokenPar.build());
                return pars;
            }
    }

4.修改spring-mvc.xml

加入：   

<bean class="com.xxxx.xxx.SwaggerConfig" />

5.修改index.html中的访问地址

URL需要改为：http://ip:port/projectname/v2/api-docs，后面这部分是不变的，如果你的项目有后缀如：do/d之类的，需要在SwaggerConfig中配置后再加上

    $(function(){
        // Begin Swagger UI call region
        const ui = SwaggerUIBundle({
            //url: "http://localhost/ql/swagger-resources/configuration/ui",
          url: requestURL+"/v2/api-docs.do",
          dom_id: '#swagger-ui',
          deepLinking: true,
          presets: [
            SwaggerUIBundle.presets.apis,
            SwaggerUIStandalonePreset
          ],
          plugins: [
            SwaggerUIBundle.plugins.DownloadUrl
          ],
          layout: "StandaloneLayout"
        })
        window.ui=ui;
    })

 

6.效果图

 

 

其他：

@ApiIgnore注解可以屏蔽类或者方法不被swagger扫描。