springcloud-zuul集成分布式API文档swagger2

关于如何在微服务中使用swagger2文档的问题,将在这篇文章中进行讲述.

很多人在单体应用中都使用过swagger2,这个是没有问题的.不过现在系统架构进入到微服务时代,很多的互联网公司都开始使用微服务架构项目,那在微服务中是如何使用swagger2的呢,假设有:会员服务,订单服务,库存服务. 我们每次进行swagger2文档都需要改变地址栏的域名或者IP吗,这毫无疑问是一个愚蠢的做法,springboot已经帮我们提供了解决方案.

实现步骤:

1. 在父工程中引入依赖

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

2. 我们以订单服务和会员服务为例,这里还需要使用到zuul网关,在zuul网关项目上加上添加一个配置类,下面的"/app-member/v2/api-docs"路径映射必须和zuul网关yml文件配置的项目路由映射路径一样.

@Configuration
public class SwaggerConfig {
    // 添加文档来源
    @Component
    @Primary
    class DocumentationConfig implements SwaggerResourcesProvider {
        @Override
        public List<SwaggerResource> get() {
            List resources = new ArrayList<>();
            //配置路由映射项目路径,其他的例如会员和订单服务的Swagger2文档的路径映射配置
            resources.add(swaggerResource("会员服务", "/app-member/v2/api-docs", "2.0"));
            resources.add(swaggerResource("订单服务", "/app-order/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;
        }
    }
}

3. 在zuul网关启动类上加上@EnableSwagger2Doc

4. 在订单和会员服务的启动类上加上@EnableSwagger2Doc

5. 配置订单和会员服务的Swagger描述(可以不配置)

swagger:
  ##联系人信息
  contact:
    email: [email protected]
    name: Jun Lee
    url: 19812543697
  ## 描述
  description: 用于学习Spring Cloud
  enabled: true
  ##排除错误路径
  exclude-path: /error/**
  host: 127.0.0.1
  license: Apache License
  title: Spring Cloud 测试会员服务接口文档
  version: 1.0.1
  ##监控所有路径
  base-path: /**

6. 然后启动zuul网关和订单和会员服务.访问zuul网关ip地址http://127.0.0.1:8100/swagger-ui.html#/ ,看到下图界面

通过切换右上角的下拉框的服务即可跳转到对应服务的文档