SpringBoot 单体服务集成Swagger

• 在Spring Boot 出现 使开发部署更加便捷，在开发接口的时候，发现提供给前端人员的接口文档需要同步和代码修改更新导致接口文件的编写是一件很繁琐的事情。
• Swagger 的出现，让开发人员不在关注接口文档的编写。

开始Springboot集成Swagger步骤

添加Swagger依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

编写Swagger的配置类

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createSwaggerApiDoc() {
        return new Docket(DocumentationType.Swagger_2)
                .apiInfo(apiInfo())
                .forCodeGeneration(true)
                .directModelSubstitute(java.nio.ByteBuffer.class, String.class)
                .genericModelSubstitutes(ResponseEntity.class)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.test.web.controller")) // 指定扫描需要被Swagger加载的controller
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("我是Swagger的描述偷")
                .description("更多详情的Swagger 请关注Swagger的官网：https://Swagger.io/")
                .termsOfServiceUrl("个人网站")
                .contact("文档创建人") // 2.7版本，参数不在是字符串，而是new Contact("名称","描述","邮箱")
                .version("1.0")
                .build();
    }

}

如上代码所示，通过 @Configuration 注解，让Spring来加载该类配置。再通过 @EnableSwagger2 注解来启用Swagger2。

通过createSwaggerApiDoc 创建Docket对象，并在此函数上面添加注解 @Bean 让Spring 进行加载 apiInfo 方法是描述Swagger文档的一些信息。如果不写。会有默认。

通过createSwaggerApiDoc 通过select() 函数返回ApiSelectorBuilder 进行指定那些接口在Swagger提醒apis(RequestHandlerSelectors.basePackage(“com.test.web.controller”)) 指定扫描的包。

直接被Swagger扫描的方式还可以使用此函数，也是跟在select() 函数后面.paths(or(regex(“/api/.*”))) 指定需要暴露给Swagger的接口 ==URL==。

Controller的编写

@RequestMapping("/api")
@RestController
public class TestController {

    @ApiOperation(value = "测试Swagger接口", notes = "测试Swagger接口")
    @RequestMapping("/test")
    public String getTest() {
        return "Api";
    }
}

@ApiOperation(value = “测试Swagger接口”, notes = “测试Swagger接口”)
该注解是描述这个接口的说明

最后启动SpringBoot 项目

访问：http:localhost:8080/Swagger-ui.html

如果这时候报错，就需要继承WebMvcConfigurationSupport
指定Swagger静态资源的访问

@Configuration
public class ServletConfig extends WebMvcConfigurationSupport {

    @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/");
    }
}

如果访问接口出现跨域问题

添加此函数到ServletConfig
此函数基于Filter的CORS配置

@Bean
public CorsFilter corsFilter() {
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    CorsConfiguration config = new CorsConfiguration();
    // 设置你要允许的网站域名，如果全允许则设为 *
    config.setAllowedOrigins(Arrays.asList("*"));
     // 如果要限制 Header 或 Method 请自行更改
    config.setAllowedMethods(Arrays.asList("GET","PUT","POST","DELETE","OPTIONS"));
    config.setAllowedHeaders(Arrays.asList("*"));
    source.registerCorsConfiguration("/api/**", config);
    // 处理Swagger请求
    source.registerCorsConfiguration("/v2/api-docs", config);
    return new CorsFilter(source);
}