构建API网关并整合Swagger
第一步:在pom.xml中引入swagger的依赖,所以主要的依赖包含下面这些:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.kye</groupId>
<artifactId>map-swagger-api-gateway</artifactId>
<version>1.0.0</version>
<packaging>jar</packaging>
<name>map-swagger-api-gateway</name>
<description>Spring Cloud In Action</description>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.5.4.RELEASE</version>
<relativePath/>
</parent>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-zuul</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-eureka</artifactId>
</dependency>
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.0.RELEASE</version>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Dalston.SR1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
第二步:在应用主类中配置swagger,具体如下:
package com.kye;
import com.spring4all.swagger.EnableSwagger2Doc;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.cloud.client.SpringCloudApplication;
import org.springframework.cloud.netflix.zuul.EnableZuulProxy;
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;
@EnableSwagger2Doc
@EnableZuulProxy
@SpringCloudApplication
public class SwaggerApplication {
public static void main(String[] args) {
new SpringApplicationBuilder(SwaggerApplication.class).web(true).run(args);
System.out.println("启动成功");
}
@Component
@Primary
class DocumentationConfig implements SwaggerResourcesProvider {
@Override
public List<SwaggerResource> get() {
List resources = new ArrayList<>();
//在这添加各个项目的信息,name是以后在swagger汇总界面的key值 ,location是 value值,version是版本号
resources.add(swaggerResource("ucenter", "/map-ucenter/ucenter/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;
}
}
}
说明:@EnableSwagger2Doc上面说过是开启Swagger功能的注解。这里的核心是下面对SwaggerResourcesProvider的接口实现部分,通过SwaggerResource添加了多个文档来源,按上面的配置,网关上Swagger会通过访问/map-ucenter/ucenter/v2/api-docs来加载文档内容,同时由于当前应用是Zuul构建的API网关,这两个请求会被转发map-ucenter服务上的/v2/api-docs接口获得到Swagger的JSON文档,从而实现汇总加载内容。
第三步:配置yml
spring:
application:
name: map-swagger-api-gateway
server:
port: 11000
eureka:
client:
serviceUrl:
defaultZone: http://localhost:8761/eureka/
#设置熔断,如果不配置会导致调用超时,无法返回数据
hystrix:
command:
default:
execution:
timeout: false
isolation:
thread:
timeoutInMilliseconds: 60000
#配置每个swagger的项目地址信息
resourcelist:
resources:
- name: server-a
location: /swagger-service-a/v2/api-docs
version: 3.0
- name: server-b
location: /swagger-service-b/v2/api-docs
version: 2.0
- name: ucenter
location: /map-ucenter/ucenter/v2/api-docs
version: 1.0
第四步写一些有关读取yml文件中每个项目中swagger地址等相关信息的java类
resource类用于读取每一个项目信息的实体类
package com.kye;
public class resource {
private String name;
private String location;
private String version;
public resource() {
}
public resource(String name, String location, String version) {
this.name = name;
this.location = location;
this.version = version;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getLocation() {
return location;
}
public void setLocation(String location) {
this.location = location;
}
public String getVersion() {
return version;
}
public void setVersion(String version) {
this.version = version;
}
}
配置读取类ResourceListConfig
package com.kye;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import java.util.ArrayList;
import java.util.List;
@Configuration
@ConfigurationProperties(prefix = "resourcelist")
public class ResourceListConfig {
private List<resource> resources =new ArrayList<>();
public List<resource> getResources() {
return resources;
}
public void setResources(List<resource> resources) {
this.resources = resources;
}
}
往swagger汇总中添加各个项目的swagger信息的配置类DocumentationConfig
package com.kye;
import org.springframework.beans.factory.annotation.Autowired;
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;
/**
* 业务描述:
* Project Name: swagger-api-gateway
* Package Name: com.kye
* Author: fuyongnan=
* Date: 2018/11/10 16:09
* Copyright (c)
*/
@Component
@Primary
class DocumentationConfig implements SwaggerResourcesProvider {
@Autowired
ResourceListConfig resourceListConfig;
@Override
public List<SwaggerResource> get() {
List resources = new ArrayList<>();
List<resource> resourceList = resourceListConfig.getResources();
for (int i = 0; i < resourceList.size(); i++) {
//在这添加各个项目的信息,name是以后在swagger汇总界面的key值 ,location是 value值,version是版本号
resources.add(swaggerResource(resourceList.get(i).getName(), resourceList.get(i).getLocation(), resourceList.get(i).getVersion()));
}
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;
}
}
测试验证:
将上面构建的两个微服务以及API网关都启动起来之后,访问网关的swagger页面,比如:http://localhost:11000/swagger-ui.html
客户端使用配置
第一步:构建一个基础的Spring Boot应用,在pom.xml中引入eureka的依赖、web模块的依赖以及swagger的依赖。主要内容如下:
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-eureka</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.0.RELEASE</version>
</dependency>
第二步:编写应用主类:
在启动类上加上 @EnableSwagger2Doc 这个注解
第三步:如果项目还需要有token认证还需要载yml文件里加以下配置:
#生成swagger的文档的包路径
swagger:
base-package: com.kye.map.ucenter
# 鉴权策略ID,对应 SecurityReferences ID
authorization:
name: Authentication
# 鉴权传递的Header参数
key-name: Authentication
# 需要开启鉴权URL的正则, 默认^.*$匹配所有URL
auth-regex: ^.*$
ui-config:
show-request-headers: true