微服务网关聚合Swagger

1、Zuul网关中的配置

1、导入依赖

<!-- swagger2 依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<!-- Swagger第三方ui依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2、application.yml添加配置

注意swagger.servers.location中的路径与zuul网关路由转发的路径匹配重点

zuul:
  routes:
    CHAOSHAN-AUTH:
     path: /auth/**
    demo:
     path: /demo/**

swagger:
  servers:
    - {name: demo,location: /demo/v2/api-docs, version: 2.0}
    - {name: auth,location: /auth/v2/api-docs, version: 2.0}

绑定配置文件中的自定义数据

@Configuration
@ConfigurationProperties(prefix = "swagger")
public class SwaggerServers {
  private static List<Server> servers = new ArrayList<>();

  public static List<Server> getServers(){
    return servers;
  }

  public void setServers(List<Server> servers){
    this.servers = servers;
  }
}

3、配置扫描微服务swagger文档

@Component
@Primary
class DocumentationConfig implements SwaggerResourcesProvider {

    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList();
        for (Server server : SwaggerServers.getServers()) {
         // 添加application.yml中的微服务资源
         resources.add(swaggerResource
                       (server.getName(),server.getLocation(),server.getVersion()));
        }
        return resources;
    }

    private SwaggerResource swaggerResource(String name, String location, String version) {
        SwaggerResource swaggerResource = new SwaggerResource();
        swaggerResource.setName(name);
        swaggerResource.setLocation(location);
        swaggerResource.setSwaggerVersion(version);
        return swaggerResource;
    }
}

4、配置Swagger

配置Swagger自动转配，以及基础信息

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .enable(true)
            .apiInfo(apiInfo());
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("Api接口测试文档")
            .description("Api接口文档说明")
            .termsOfServiceUrl("http://localhost:8001")
            .contact(new Contact("xxx", "https://xxx", "xxx@qq.com"))
            .version("1.0")
            .build();
  }

  @Bean
  UiConfiguration uiConfig() {
    return new UiConfiguration(null, "list", "alpha", "schema",
            UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L);
  }

2、微服务中的配置

1、导入依赖

<!-- swagger2 依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<!-- Swagger第三方ui依赖 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

2、配置Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
  public Docket createRestApi() {
    //添加head参数配置start
    return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())
            .select()
        	// 配置包扫描
            .apis(RequestHandlerSelectors.basePackage("com.xxx"))
            .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("demo模块")
            .description("demo模块接口API文档")
            .contact(new Contact("xxx", "https://xxx", "xxx@qq.com"))
            .version("2.0")
            .build();
  }
}

3、SpringSecurity环境放行Swagger

@Configuration
@EnableGlobalMethodSecurity(securedEnabled = true,prePostEnabled = true)
public class WebSecurityConfig extends WebSecurityConfigurerAdapter {

  @Bean
  public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
  }

  @Override
  protected void configure(HttpSecurity http) throws Exception {
    http.csrf().disable()
            .authorizeRequests()
            .anyRequest().authenticated()
            .and()
            .formLogin();
  }

  @Override
  public void configure(WebSecurity web) throws Exception {
    web.ignoring().antMatchers("login","/logout",
            "/css/xx",
            "/js/xx",
            "/index.html",
            "favicon.ico",
            "/doc.html",
            "/webjars/**","/demo/v2/api-docs",//swagger api json
            "/swagger-resources/configuration/ui",//用来获取支持的动作
            "/swagger-resources",//用来获取api-docs的URI
            "/swagger-resources/configuration/security",//安全选项
            "/swagger-ui.html", "/doc.html");
  }
}

4、Oauth2环境放行Swagger

在资源服务器中进行放行，授权服务器如果也聚合了Swagger需要放行 WebSecurityConfigurerAdapter的权限，和上边一样

@Configuration
@EnableResourceServer
public class ResouceServerConfig extends ResourceServerConfigurerAdapter {

......

  @Override
  public void configure(HttpSecurity http) throws Exception {

    http
            .authorizeRequests()
            .antMatchers("/v2/**",//swagger api json
                    "/css/**", "/js/**", "/images/**", "/webjars/**", "**/favicon.ico", "/index",
                    "/swagger-resources/configuration/ui",//用来获取支持的动作
                    "/swagger-resources",//用来获取api-docs的URI
                    "/swagger-resources/configuration/security",//安全选项
                    "/swagger-ui.html", "/doc.html").permitAll()
            .antMatchers("/**").access("#oauth2.hasScope('ROLE_ADMIN')")
            .and().csrf().disable()
            // 基于token，所以要关闭session
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);
  }

}

5、效果展示

3、Swagger实战场景

1、自定义注解实现接口跳过Swagger扫描

自定义注解

@Target(value = {ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME) // 运行时有效
public @interface MyAnnotationSwagger {
  String value() default "";
}

添加配置

@Bean
public Docket createRestApi() {
  return new Docket(DocumentationType.SWAGGER_2)
          // .enable(true)
          .apiInfo(apiInfo())
          .select()
          .apis(RequestHandlerSelectors.basePackage("com.chaoshan"))
          .apis(Predicates.not( // 取反
              // 当方法上有MyAnnotationSwagger注解时，返回true
                  RequestHandlerSelectors.withMethodAnnotation( 
                          MyAnnotationSwagger.class)))
          .build();
}


// 添加该注解后，此接口不会展示在接口文档上
  @MyAnnotationSwagger
  @ApiOperation(value = "r1接口", notes = "测试接口r1")
  @GetMapping(value = "/r1")
  public String r1( String a) {
    return a + "资源访问1";
  }

2、Swagger注解的使用

注意只有在接口中返回了该实体后，才会在接口文档上显示该实体信息

@ApiModel 标注在实体类上，不是Controller

@ApiModelProperties 标注在属性上

@Data
@ApiModel(value = "自定义实体user",description = "存储用户数据")
public class User {
  /**
   * 主键
   */
  @ApiModelProperty(name = "主键(id)",value = "主键",required = false,example = "111",hidden = false)
  private Long id;
}

@Api 标注在Controller上

@ApiOperation 标注在方法上

@ApiParam 标注在方法的参数上，或者说添加在参数前面

@ApiImplicitParam 标注在方法上，同样描述的是方法的参数，与@ApiParam的区别在于，@ApiParam是放在参数旁，而@ApiImplicitParam是放在方法上的，不过需要绑定参数名

@ApiImplicitParams 标注在方法上，如果方法有多个参数，需要使用这个值是数组类型的@ApiImplicitParam

@GetMapping(value = "/r3")
@ApiOperation(value = "r3接口")
@ApiImplicitParam(name = "m", value = "参数描述m", required = false, paramType = "String1")
public String r3(@ApiParam(value = "m1") String m) {
    return "r3";
}

@GetMapping(value = "/r4")
@ApiOperation(value = "r4接口")
@ApiImplicitParams(
    value = { @ApiImplicitParam(name = "m", value = "参数m描述", required = false, paramType = "Integer"),
             @ApiImplicitParam(name = "n", value = "参数n描述", required = true, paramType = "String(字符串)")}
)
public String r4(String m, String n) {
    return "r4";
}

如果你对本文的内容有疑问或者其他方面的见解，欢迎到评论区里留言