Swagger2 Zuul 整合

ゝ一世哀愁。 2021-10-01 09:04 284阅读 0赞

## 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
        
        <table> 
         <thead> 
          <tr> 
           <th style="text-align:center">属性</th> 
           <th style="text-align:center">描述</th> 
          </tr> 
         </thead> 
         <tbody> 
          <tr> 
           <td style="text-align:center">description</td> 
           <td style="text-align:center">API资源描述</td> 
          </tr> 
          <tr> 
           <td style="text-align:center">tags</td> 
           <td style="text-align:center">API标签</td> 
          </tr> 
         </tbody> 
        </table>
     *  **@ApiOperation**：注解在方法上,描述接口操作
        
        <table> 
         <thead> 
          <tr> 
           <th style="text-align:center">属性</th> 
           <th style="text-align:center">描述</th> 
          </tr> 
         </thead> 
         <tbody> 
          <tr> 
           <td style="text-align:center">value</td> 
           <td style="text-align:center">接口说明</td> 
          </tr> 
          <tr> 
           <td style="text-align:center">httpMethod</td> 
           <td style="text-align:center">接口请求方式</td> 
          </tr> 
          <tr> 
           <td style="text-align:center">response</td> 
           <td style="text-align:center">接口返回类型</td> 
          </tr> 
          <tr> 
           <td style="text-align:center">notes</td> 
           <td style="text-align:center">接口提醒说明</td> 
          </tr> 
         </tbody> 
        </table>
     *  **@ApiResponses**：响应描述集
     *  **@ApiResponse**：响应描述
     *  **@ApiModel**：描述返回对象
     *  **@ApiModelProperty**：描述对象的属性
        
        <table> 
         <thead> 
          <tr> 
           <th style="text-align:center">属性</th> 
           <th style="text-align:center">描述</th> 
          </tr> 
         </thead> 
         <tbody> 
          <tr> 
           <td style="text-align:center">notes</td> 
           <td style="text-align:center">属性描述</td> 
          </tr> 
          <tr> 
           <td style="text-align:center">hidden</td> 
           <td style="text-align:center">是否显示</td> 
          </tr> 
         </tbody> 
        </table>
     *  **@ApiImplicitParams**：参数描述集
     *  **@ApiParam**：请求参数的描述
        
        <table> 
         <thead> 
          <tr> 
           <th style="text-align:center">属性</th> 
           <th style="text-align:center">描述</th> 
          </tr> 
         </thead> 
         <tbody> 
          <tr> 
           <td style="text-align:center">name</td> 
           <td style="text-align:center">参数名name</td> 
          </tr> 
          <tr> 
           <td style="text-align:center">value</td> 
           <td style="text-align:center">参数说明</td> 
          </tr> 
         </tbody> 
        </table>
     *  **@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][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][http_localhost_8081_swagger-ui.html] 时，可在下拉菜单中选择不同微服务的API文档

![9434708-3368da359210bc86.png][]

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

[https_gitee.com_LinYuanTongXue_DEMO-ZUUL-SWAGGER2]: https://link.jianshu.com?t=https%3A%2F%2Fgitee.com%2FLinYuanTongXue%2FDEMO-ZUUL-SWAGGER2
[http_localhost_8081_swagger-ui.html]: https://link.jianshu.com?t=http%3A%2F%2Flocalhost%3A8081%2Fswagger-ui.html
[9434708-3368da359210bc86.png]: /images/20210811/6f562d785a9b4d178702d7cd048dd3c3.png