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

刺骨的言语ヽ痛彻心扉 2022-04-15 03:22 233阅读 0赞

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