Swagger2 配置在线接口文档

swagger2的使用优点：

  1、有时候接口太多，维护力度太多；swagger减少了这些麻烦。

  2、直接在线测试接口

swagger2的依赖配置步骤：

1、添加maven依赖：

      
            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        
        
            com.fasterxml.jackson.core
            jackson-annotations
            2.9.8
        

  2、添加 SwaggerConfig.java 启动配置

package com.ppfuns.auth.api.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.util.UriComponentsBuilder;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseMessageBuilder;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ResponseMessage;
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;

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

@Component
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan("com.ppfuns.auth.api.controller")  //指定扫描的controller目录
public class SwaggerConfig {
//    @Value("${swagger.enable}")
    private boolean enableSwagger =true; //enableSwagger是多环境配置开关，一般生产环境中不想打开swagger的uil界面，就可以让其为false
    @Bean
    public Docket createAPI() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(enableSwagger)
                .forCodeGeneration(true)
                .pathProvider(new CustRelativePathProvider()) //重定义接口路径
                .select()
                .apis(RequestHandlerSelectors.any())
//                过滤生成链接
                .paths(PathSelectors.any())
                .build()
                .pathMapping("/")
//                .globalResponseMessage(RequestMethod.GET, getResponseMessageList())
//                .globalResponseMessage(RequestMethod.POST, getResponseMessageList())
//                .globalResponseMessage(RequestMethod.PUT, getResponseMessageList())
//                .globalResponseMessage(RequestMethod.DELETE, getResponseMessageList())
                .apiInfo(apiInfo());
    }
   private List getResponseMessageList(){ //定义response结果
       List responseMessageList = new ArrayList<>();
       responseMessageList.add(new ResponseMessageBuilder().code(404).message("找不到资源").responseModel(new ModelRef("Error")).build());
       responseMessageList.add(new ResponseMessageBuilder().code(409).message("业务逻辑异常").responseModel(new ModelRef("Error")).build());
       responseMessageList.add(new ResponseMessageBuilder().code(422).message("参数校验异常").responseModel(new ModelRef("Error")).build());
       responseMessageList.add(new ResponseMessageBuilder().code(500).message("服务器内部错误").responseModel(new ModelRef("Error")).build());
       responseMessageList.add(new ResponseMessageBuilder().code(503).message("Hystrix异常").responseModel(new ModelRef("Error")).build());
       return responseMessageList;
   }
    private ApiInfo apiInfo() {
        Contact contact=new Contact("SunnJam","http://localhost:8888/","[email protected]");
        ApiInfo apiInfo = new ApiInfoBuilder().
                license("Apache License Version 2.0").
                title("API接口").
                description("API SWAGGER 接口文档目录").
                contact(contact).
                version("1.0.0").build();

        return apiInfo;
    }
    /**
     *对接口路径进行规划和定义； 这里在项目中swagger测试时，接口路径以.json结尾
   **/
    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 operationPath + ".json";
        }

        @Override
        protected String applicationPath() {
            return ROOT;
        }

        @Override
        protected String getDocumentationPath() {
            return ROOT;
        }
    }

}

3、web配置（由于接口路径加了后缀，对swagger2的接口不做后缀处理）

    dispatcher
    org.springframework.web.servlet.DispatcherServlet
    
      contextConfigLocation
      
        classpath:spring/spring-mvc.xml
      
    
    1
  
  
    dispatcher
    *.htm
    *.json
    *.xml
    *.m3u8
    /v2/api-docs
    /swagger-resources/configuration/ui
    /swagger-resources
    /swagger-resources/configuration/security
    /swagger-resources/**

4、配置静态访问路径（pring-mvc.xml）

5、swagger访问：

http://localhost:8888/swagger-ui.html

http://localhost:8888/v2/api-docs

上述已完成对swagger2接口的配置；如果想使用swagger的html和pdf文件的生成：https://blog.csdn.net/jiandequn/article/details/94720045