Swagger2 Zuul 整合

Swagger2

Swagger2是一个RESTful接口进行描述和展示的工具，可以通过 springfox-swagger2 整合，生成相应的文档，需引入两个库：

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

通过 @Configuration 注解为配置类，通过 @EnableSwagger2 启动 Swagger2，创建 Docket 的 Bean，通过 apiInfo() 方法创建api配置信息，select() 方法会返回一个ApiSelectorBuilder 实例用来控制哪些借口暴露给 Swagger 展现

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.linyuan.paymentserver"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("描述")
                .termsOfServiceUrl("http://localhost:8083")
                .contact("林塬")
                .version("1.0")
                .build();
    }

}

我们还可以在Controller上添加相应注解来为接口提供相应描述：
- @Api：标记一个Controller类做为swagger
  
  属性描述
  
  description API资源描述
  
  tags API标签
- @ApiOperation：注解在方法上,描述接口操作
  
  属性描述
  
  value 接口说明
  
  httpMethod 接口请求方式
  
  response 接口返回类型
  
  notes 接口提醒说明
- @ApiResponses：响应描述集
- @ApiResponse：响应描述
- @ApiModel：描述返回对象
- @ApiModelProperty：描述对象的属性
  
  属性描述
  
  notes 属性描述
  
  hidden 是否显示
- @ApiImplicitParams：参数描述集
- @ApiParam：请求参数的描述
  
  属性描述
  
  name 参数名name
  
  value 参数说明
- @ApiImplicitParam：注解在方法上，对一组参数描述
  - paramType：查询参数类型
    - path（以地址形式提交数据）
    - query（直接跟参数完成自动映射赋值）
    - body（以流方式提交，支持POST）
    - header（参数在request headers里提交）
    - form（以form表单形式提交）
  - dataType：参数数据类型
  - name：接收参数名
  - value：参数的描述
  - required：是否必须填

属性	描述
description	API资源描述
tags	API标签

属性	描述
value	接口说明
httpMethod	接口请求方式
response	接口返回类型
notes	接口提醒说明

属性	描述
notes	属性描述
hidden	是否显示

属性	描述
name	参数名name
value	参数说明

Swagger2 与 Zuul 整合

使用 Zuul 作为分布式系统网关，整个系统的文档
demo 源码：https://gitee.com/LinYuanTongXue/DEMO-ZUUL-SWAGGER2

项目结构

eureka-server ：服务注册中心，端口 8080
zuul-server：网关，端口 8081
payment-server：支付系统，端口 8082
order-server：订单系统，端口 8083

实现方法

zuul-server 路由配置

zuul:
  routes:
    payment-server:
      path: /pay/**
    order-server:
      path: /order/**

zuul-server 的 Swagger 配置类 SwaggerConfig

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("分布式购物系统")
                .description("购物系统接口文档说明")
                .termsOfServiceUrl("http://localhost:8081")
                .contact(new Contact("林塬", "", "765371578@qq.com"))
                .version("1.0")
                .build();
    }
}

zuul-server Swagger 资源文档配置类 DocumentationConfig

/**
    通过配置资源文档，在首页下拉框选择订单系统时，会请求 http://localhost:8081/order/v2/api-docs 获取文档详情，zuul 根据路由配置，会将 /order/** 请求转发到路由 serviceId 为 order-server 系统上
**/

@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider{

    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList<>();
        resources.add(swaggerResource("订单系统", "/order/v2/api-docs", "2.0"));
        resources.add(swaggerResource("支付系统", "/pay/v2/api-docs", "2.0"));
        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;
    }
}

payment-server 与 order-server 配置 Swagger 与原先没任何区别

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.linyuan.orderserver"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("购物系统-订单模块")
                .description("购物系统订单模块接口文档说明")
                .termsOfServiceUrl("http://localhost:8083")
                .contact(new Contact("林塬", "", "765371578@qq.com"))
                .version("1.0")
                .build();
    }
}

测试，当访问 http://localhost:8081/swagger-ui.html 时，可在下拉菜单中选择不同微服务的API文档

WX20171228-153005@2x.png

也可使用通过遍历路由方式自动添加所有微服务 API 文档

@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider{

    private final RouteLocator routeLocator;

    public DocumentationConfig(RouteLocator routeLocator) {
        this.routeLocator = routeLocator;
    }

    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList<>();
        List<Route> routes = routeLocator.getRoutes();
        System.out.println(Arrays.toString(routes.toArray()));
        routes.forEach(route -> {
            resources.add(swaggerResource(route.getId(), route.getFullPath().replace("**", "v2/api-docs"),"2.0"));
        });
        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;
    }
}

修改 serviceId 与路由之间的相互映射

@Configuration
public class ZuulConfig {
    //自定义 serviceId 和路由之间的相互映射
    @Bean
    public PatternServiceRouteMapper serviceRouteMapper() {
        return new PatternServiceRouteMapper(
                "(?<project>^.+)-(?<subProject>.+$)",
                "${project}/${subProject}");
    }
}