关于java:Springboot集成Swagger2及常见配置无坑版

本文出自《愚公要移山》

收录于《Springboot 专题》中

这种整合的文章的确曾经烂大巷了，写他一方面是补充我的 springboot 系列，另一方面的确还有一部分小伙伴没用过。最重要的是，如果你遗记了这种整合的代码。能够随时查阅。

前言

当初的开发基本上都是前后端拆散，前后端交互都是通过 API 文档。有了 API 文档大家各自开发，互不烦扰。

1、传统形式

传统形式是文档设计好之后，别离发给前端和后端人员。这样有个毛病，接口信息一旦变动，文档就须要从新发送给前后端人员。无奈做到实时。所以浪费时间和精力。

2、swagger 形式

咱们的后盾利用集成了 swagger 之后，会主动暴露出咱们的接口，而且这个接口模式还是通过 restful 格调公布的。一旦后端的接口有变动，会立即显示进去，因而极大地提高了效率。

OK，基本上一句话就能够总结他的益处，那就是后端写的 api 文档能够通过 swagger 的模式实时的公布进去，供前端人员查看。

3、其余形式

swagger 的页面说实话长得不难看，也有一些其余的计划，不是有很多 bug，就是免费。目前 swagger 是应用的最多的。我目前也正在做这个样的开源我的项目，基于 swagger 做出相似于其余计划的页面，而且性能更加的弱小。

一、代码整合

前提条件是要新建一个 springboot 我的项目。这点就不演示了。

第一步：增加依赖

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

2.9.2 的版本是用的最多的，具体的能够间接去 maven 的官网去搜寻，找一个使用量最多的版本即可。

第二步：配置

新建 config 包，创立 SwaggerConfig 类

@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2)
             .apiInfo(apiInfo())
             .select()
             // 为以后包门路, 控制器类包
             .apis(RequestHandlerSelectors.basePackage("com.fdd.controller"))
            .paths(PathSelectors.any())
             .build();}
    // 构建 api 文档的详细信息函数
    private ApiInfo apiInfo() {return new ApiInfoBuilder()
            // 页面题目
           .title("XX 平台 API 接口文档")
            // 创建人
           .contact(new Contact("冯冬冬", "http://www.javachat.cc",  
                 "3049352171@qq.com"))
           // 版本号
          .version("1.0")
           // 形容
          .description("零碎 API 形容")
          .build();}

这里的配置也比较简单。这里有很多选项供咱们去配置。如果咱们的我的项目有多个组，只须要创立多个 Docket 即可。这时候扫描的包换成每个组的包门路。

第三步：controller 类中配置

新建一个 controller 包，而后创立 HelloController 类

@RestController 
public class HelloController {@GetMapping(value = "/user")
    public User getUser(){return new User("愚公要移山","123456");
    }
    @ApiOperation("能够指定参数的 API")
    @PostMapping("/param")
    public String hello2(@ApiParam("用户名") String name){return "hello" + name;}
}

这里咱们能够看出，应用注解就能够对这个类、办法、字段等等进行解释阐明。其余的字段还有很多，在应用的时候会有相应的提醒，能够本人试一遍：

第四步：查看成果

拜访:http://127.0.0.1:8080/swagger-ui.html 即可。

这里就是最终的展现成果。OK，到这一步基本上就集成进来了。上面说一下可能会遇到的配置。

三、常见其余问题

1、Spring Security – 配置免认证拜访

有时候咱们的 Springboot 集成了 SpringSecurity，这时候如果拜访 swagger 的地址会主动跳转到登录页面。这是因为 SpringSecurity 对其进行了拦挡。为此咱们只须要在咱们的 SpringSecurity 配置一下进行放行即可。

当初配置一下，进行放行。在 config 包下新建一个 SpringSecurityConfig 类

@EnableWebSecurity
public class SpringSecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .authorizeRequests()
                .antMatchers("/swagger-ui.html").permitAll()
                .antMatchers("/webjars/**").permitAll()
                .antMatchers("/swagger-resources/**").permitAll()
                .antMatchers("/v2/*").permitAll()
                .antMatchers("/csrf").permitAll()
                .antMatchers("/").permitAll()
                .anyRequest().authenticated()
                .and()
                .formLogin()
        ;
    }
}

此时就能够失常的拜访了。

2、为 swagger 设置 jwt

这种形式比较简单，只须要一步即可。批改咱们的 swaggerConfig 类即可。

@Configuration
public class Swagger2Config {
    @Bean
    public Docket api() {return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();}
    // 构建 api 文档的详细信息函数
    private ApiInfo apiInfo() {return new ApiInfoBuilder()
                // 页面题目
                .title("XX 平台 API 接口文档")
                // 创建人
                .contact(new Contact("冯冬冬", "http://www.javachat.cc",
                        "3049352171@qq.com"))
                // 版本号
                .version("1.0")
                // 形容
                .description("零碎 API 形容")
                .build();}
    private ApiKey apiKey() {return new ApiKey("JWT", "Authorization", "header");
    }
    private SecurityContext securityContext() {return SecurityContext.builder().securityReferences(defaultAuth()).build();}
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope 
         = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
    }
}

加了一些 token 验证的代码，比较简单，对于 JWT 的货色，能够私下理解。这里不赘述了。

3、暗藏 Endpoint

有时候本人写的 controller，或者是 controller 外面的接口办法不想让前端人员看到，咱们能够暗藏即可。

第一：暗藏整个 controller

@RestController
public class MyController {// 办法}

第二：暗藏某个接口办法 1

@ApiOperation(value = "形容信息")
@GetMapping("/getAuthor")
public String getAuthor() {return "愚公要移山";}

第三：暗藏某个接口办法 2

@GetMapping("/get")
public LocalDate getDate() {return LocalDate.now();
}

OK，很多配置基本上就到这了。后续会持续补充。