Spring Boot之Swagger2集成

Posted 2021-01-16 N!CE波

一、Swagger2简单介绍

　　Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

 

二、Spring Boot集成Swagger2步骤

1）引入Swagger2的Maven坐标

 <!--swagger-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.8.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.8.0</version>
            </dependency>

 

2) 加入Swagger2的Java配置类

import org.springframework.context.annotation.Configuration;
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;

/**
 * @author zhangboqing
 * @date 2018/8/6
 *
 * swagger2配置
 *
 * 访问地址：
 * http://localhost:8080/swagger-ui.html
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {


    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                //当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.zbq.springbootbase.controller"))
                .paths(PathSelectors.any()).build();

    }

    //构建api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("springboot-base-frame,使用Swagger2构建RESTful API")
                //创建人
                .contact(new Contact("张波清", "[e-mail]", ""))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();


    }

}

 

3）在Controller方法上加上  @ApiOperation(value="测试", notes="这是一个简单测试方法"),再不用加任何注解。

/**
 * @author zhangboqing
 * @date 2018/9/24
 */
@RestController
public class TestController {

    @ApiOperation(value="测试", notes="这是一个简单测试方法")
    @PostMapping(value = "/test")
    public String test(@RequestHeader String myHeader,String myName) {
        System.out.println("----------->header测试");

        System.out.println(myHeader);
        System.out.println(myName);
        return myHeader;
    }

}

4）若使用了Spring Boot 的拦截器，需要过滤Swagger，确保它不被拦截

　　加入如下标记为蓝色的过滤配置，就可以了

/**
 * @author zhangboqing
 * @date 2018/8/7
 *
 * 注册拦截器
 */
@Configuration
public class ApiSecurityConfig2 implements WebMvcConfigurer {



    @Bean
    LoggingInterceptor loggingInterceptor() {
        return new LoggingInterceptor();
    }

    /**
     * 拦截请求
     *
     * @param registry
     */
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        //注册日志拦截器
        registry.addInterceptor(loggingInterceptor())
                //添加需要拦截的路径
                .addPathPatterns("/**")
                .excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**");

    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

    /**
     * 跨域配置
     *
     * @param registry
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
//        registry.addMapping("/**")
//                // TODO 这里跨域最好配置域名
//                .allowedOrigins("*")
//                .maxAge(3600)
//                .allowCredentials(true)
//                .allowedMethods("GET", "POST", "OPTIONS");
    }
}

 

 

 

三、效果展示 

启动你的项目，访问Swagger2文档地址：http://localhost:8080/swagger-ui.html