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：是否必须填

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