SpringCloud（七）Zuul + Swagger 搭建分布式API接口文档管理平台

目录

1.传统的API文档编写的缺点

2.Swagger的优点

3.Swagger入门

4.Zuul + Swagger 实现分布式API接口管理平台

4.1搭建order项目

4.2搭建member项目

4.3.搭建zuul项目

4.4.启动

---

 

 

1.传统的API文档编写的缺点

1.对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；

2.API接口返回信息不明确

3.大公司中肯定会有专门文档服务器对接口文档进行更新。

4.缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等

5.接口文档太多，不便于管理

为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

 

2.Swagger的优点

1.功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；

2.及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；

3.整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

 

 

3.Swagger入门

Swagger2.0集成配置

1）创建maven工程：springboot-swagger

2）pom文件

    4.0.0
    com.itmayiedu
    springboot-swagger
    1.0-SNAPSHOT
    
    
        org.springframework.boot
        spring-boot-starter-parent
        2.0.1.RELEASE
    
    
        
            org.springframework.boot
            spring-boot-starter-web
        
        
        
            io.springfox
            springfox-swagger2
            2.8.0
        
        
            io.springfox
            springfox-swagger-ui
            2.8.0
        
    

3）SwaggerConfig

package com.itmayiedu.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

   // @EnableSwagger2 开启Swagger2
   @Bean
   public Docket createRestApi() {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
            // api扫包范围
           .apis(RequestHandlerSelectors.basePackage("com.itmayiedu.controller")).paths(PathSelectors.any()).build();
   }

   //
   private ApiInfo apiInfo() {
      return new ApiInfoBuilder().title("Swagger课程学习")  // 文档名称
            .description("Swagger课程学习 2019.12.15")  // 文档描述
            .termsOfServiceUrl("http://www.itmayiedu.com")  // 地址
            // .contact(contact)
            .version("1.0")  //版本号
            .build();
   }

}

• @EnableSwagger2 开启Swagger2
• api扫包范围不要搞错了，否则会找不到对应的controller

4）SwaggerController

package com.itmayiedu.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Api("Swagger类描述")
@RestController
public class SwaggerController {

    @ApiOperation("Swagger接口描述")
    @GetMapping("/swaggerIndex")
    @ApiImplicitParam(name = "username",value = "用户名",required = true,dataType = "String")
    public String swaggerIndex(String username){
        return username;
    }
}

注意：

• 不要使用RequestMapping注解了，此注解如果没有对应的Method属性，表示所有的请求方式都可以访问，而使用对应的GetMapping或者PostMapping等，指定特定的请求方式。
• 可以不写参数，不用@ApiImplicitparam注解，可以写一个参数，用@ApiImplicitparam注解，可以写多个参数，用用@ApiImplicitparams注解

5）启动类

package com.itmayiedu;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ApplicationApp {
    public static void main(String[] args) {
        SpringApplication.run(ApplicationApp.class, args);
    }
}

6）application.yml

###服务端口号
server:
  port: 8080

7）浏览器访问：http://localhost:8080/swagger-ui.html#/

8）可以查看接口信息：点击Swagger接口描述

 

9）可以进行接口测试（取代postman等测试工具）

点击"try it out" ==> 输入参数值 ==> 点击“Excute”，进行测试

查看返回结果

 

 

4.Zuul + Swagger 实现分布式API接口管理平台

在微服务中，每一个服务都会集成一个swagger，这称作swagger集群；但是每一个服务都会有一个地址，我们不可能查看一个服务的文档，就换一个地址，这样很显然是不合适的。这个时候我们就需要把所有的swagger的进行合成到同一台服务器中，如何实现呢，我们有两种方式可以选择：

1）使用Nginx + Swagger，在Nginx里配置，以项目区分，不同的项目跳转到不同的接口文档

2）使用Zuul + Swagger，根据对应的服务，转发请求，调用对应的服务接口文档

Springboot支持对swagger管理，只需要在zuul网关中添加对应服务的swagger文档即可。

 

我们基于上一篇文档搭建zuul网关的项目来搭建 zuul + swagger 的项目，代码略有出入，以我上传到码云的代码为准，本篇文章只写主要代码。

使用到的项目：

 

4.1搭建order项目

order项目端口号：8001

1）添加swagger依赖

    com.spring4all
    swagger-spring-boot-starter
    1.7.0.RELEASE

我们发现跟之前做swagger入门项目的依赖不同，这是springboot对swagger的集成包

2）application.yml 添加扫包范围

#扫包范围
swagger:
  base-package: com.itmayiedu.api.controller

3）Controller

package com.itmayiedu.api.controller;

import com.spring4all.swagger.EnableSwagger2Doc;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@EnableSwagger2Doc
@Api("订单服务接口")
public class IndexController {

    @GetMapping("/")
    @ApiOperation("订单首页接口")
    public String index(){
        return "我是订单项目！";
    }
}

@EnableSwagger2Doc:开启Swagger2Doc

 

 

4.2搭建member项目

member项目端口号：8002

1）添加swagger依赖

注：swagger的依赖其实是加在parent项目里的，如果是不同的项目，都需要添加依赖。

2）application.yml 添加扫包范围

#扫包范围
swagger:
  base-package: com.itmayiedu.api.controller

3）Controller

package com.itmayiedu.api.controller;

import com.spring4all.swagger.EnableSwagger2Doc;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@EnableSwagger2Doc
@Api("会员服务接口")
public class IndexController {

    @GetMapping("/")
    @ApiOperation("会员首页接口")
    public String index(){
        System.out.println("我是会员项目");
        return "我是会员项目！";
    }
}

@EnableSwagger2Doc:开启Swagger2Doc

 

 

4.3.搭建zuul项目

zuul项目端口号：80

1）项目结构

2）添加swagger依赖

    com.spring4all
    swagger-spring-boot-starter
    1.7.0.RELEASE

3）DocumentationConfig

package com.itmayiedu.config;

import com.spring4all.swagger.EnableSwagger2Doc;
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;

@Component
@Primary
@EnableSwagger2Doc
public class DocumentationConfig implements SwaggerResourcesProvider {

   @Override
   public List get() {
      List resources = new ArrayList<>();
      resources.add(swaggerResource("会员服务接口文档", "/api-member/v2/api-docs", "2.0"));
      resources.add(swaggerResource("订单服务接口文档", "/api-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;
   }
}

这个文件是swagger的核心文件：

1.实现 SwaggerResourcesProvider 接口，重新get方法

2.@EnableSwagger2Doc 开启Swagger2Doc

3.此参数可自定义，对应之后UI中的服务文档名称

4.此参数必须与application.yml文件中的值对应。

 

4.4.启动

1）依次启动eureka，order，member，zuul项目

2）浏览器访问：http://localhost/swagger-ui.html#

3）分别进入对应的接口，测试，成功！

swagger还可以导出文档，此处就不做介绍了。

 

 

后文：代码已上传到码云 https://gitee.com/xuruanshun/springcloud.git