swagger系列教程二之汇总使用文档

构建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