zuul网关管理整个微服务接口文档

image.png

zuul网关源码地址: https://github.com/liangxifeng833/springcloud/tree/master/configCenter/zuul_gateway
会员服务源码地址: https://github.com/liangxifeng833/springcloud/tree/master/parent/api-member-service-impl
订单服务源码地址:https://github.com/liangxifeng833/springcloud/tree/master/parent/api-order-service-impl

注意: 以上服务依赖eureka和springCloud分布式配置中心服务端,启动以上服务之前必须先启动eureka和configServer

eureka服务源码地址: https://github.com/liangxifeng833/springcloud/tree/master/eureka/springcloud-eureka-service
configServer源码地址: https://github.com/liangxifeng833/springcloud/tree/master/configCenter/config2.0_server

具体会员/订单的服务项目上pom中引入依赖有两种方式

• 第一: 引入swagger相关的两个依赖, 注意: 需要自己配置SwaggerConfig

        <!--swagger2 rest api -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency

• 第二: 引入springBoot整个Swagger依赖, swagger2-spring-boot-starter,这里只有一个依赖, springBoot已经整合好配置了, 所以不需要自己单独配置: SwaggerConfig

        <!-- spring-boot swagger依赖 -->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.7.0.RELEASE</version>
        </dependency>

修改会员以及订单服务的 application.yml 添加扫包配置:

• 修改application.yml,新增:

swagger:
  base-package: api.member.service.impl

项目启动文件新增如下注解

//开启swagger生成api文档的注解
@EnableSwagger2Doc

在订单服务controller中写接口注解(注意:必须在controller中才会生效)

• 修改会员服务的 MemberServiceImpl.java

package api.member.servcie.impl;

import api.common.base.BaseApiService;
import api.common.base.ResponseBase;
import api.member.entity.User;
import api.member.service.IMemberServcie;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

/**
 * 会员接口实现,注意：实现的是api.member.servcie项目中的api接口
 */
@RestController
//swagger接口文档相关注解
@Api(tags = "会员服务接口")
public class MemberServiceImpl extends BaseApiService implements IMemberServcie {
    @Value("${server.port}")
    private Integer serverPort;

    @ApiOperation("会员服务默认方法")
    @GetMapping("/")
    public String index() {
        return "我是会员服务,port="+serverPort;
    }

    @Override
    //swagger接口文档相关注解--start
    @ApiOperation("查询会员接口")
    @ApiImplicitParam(name="name",value = "会员名称",defaultValue = "用户信息参数",required = true)
    //swagger接口文档相关注解--end
    @GetMapping("/getMember")
    public User getMember(@RequestParam("name") String name) {
        User user = new User();
        user.setName(name+serverPort);
        user.setAge(20);
        return user;
    }

    @GetMapping("/getUserInfo")
    @Override
    public ResponseBase getUserInfo() {
        try {
            //会员服务接口产生1.5秒的延迟
            Thread.sleep(1500);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
        return setResultSuccess("调用会员服务接口成功...");
    }

    @PostMapping("/postDemo")
    public ResponseBase postDemo(@RequestBody Map<String,Object> params)
    {
        return setResultSuccess("调用成功");
    }

• 启动会员服务,然后请求: http://127.0.0.1:8102/swagger-ui.html
  image.png

订单服务的配置与会员服务完全一样

• 配置完成后请求: http://127.0.0.1:8103/swagger-ui.html
  image.png

配置统一入口Zuul网关项目

• pom中加入的依赖

        <!-- spring-boot swagger依赖 -->
        <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.7.0.RELEASE</version>
        </dependency>

• 项目启动文件ZuulGatewayApplication.java开启swagger注解:

//开启swagger文档
@EnableSwagger2Doc  

• 新建DocumentationConfig.java类,内容:

package zuul_gateway;

import org.springframework.cloud.netflix.zuul.filters.RouteLocator;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;

import java.util.ArrayList;
import java.util.List;

/**
 * zuul整合swagger所用类
 * 添加文档来源吗
 */
@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider {
    private final RouteLocator routeLocator;

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

    /**
     * 配置所有的微服务
     *
     * @return
     */
/*    @Override
    public List<SwaggerResource> get() {
        List<SwaggerResource> resources = new ArrayList<>();
        List<Route> routes = routeLocator.getRoutes();
        routes.forEach(route -> {
            resources.add(swaggerResource(route.getId(), route.getFullPath().replace("**", "v2/api-docs"), "1.0"));
        });
        return resources;
    }*/

    /**
     * 配置特定的微服务
     * @return
     */
    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList<>();
        //配置会员服务和订单服务文档路径, 注意: api-member和api-order必须与application路由中对应的会员和订单服务名称一致
        resources.add(swaggerResource("会员服务", "/api-member/v2/api-docs", "1.0"));
        resources.add(swaggerResource("订单服务", "/api-order/v2/api-docs", "1.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;
    }
}

• 启动网关服务后,访问: http://127.0.0.1:8302/swagger-ui.html, 可以选择 Select a spec选择不同服务的文档, 也就实现了文档的统一入口管理.
  image.png