Gateway集成swagger3.0

傷城~ 2022-10-28 10:19 332阅读 0赞

#### 一、依赖 ####

<dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-boot-starter</artifactId>
                    <version>3.0.0</version>
                </dependency>
                
    			 
                <dependency>
                    <groupId>com.github.xiaoymin</groupId>
                    <artifactId>swagger-bootstrap-ui</artifactId>
                    <version>1.9.6</version>
                </dependency>

每一个微服务和 gateway都要这个依赖

### 微服务 的swagger配置 ###

### 第一个版本 ###

/** * 文件名: SwaggerConfig * 创建者: 友 * 创建日期: 2021/1/25 11:00 * 邮箱: 1738743304.com ! * 描述: TODO */
    @Configuration
    public class SwaggerConfig { 
    
    	@Value("${swagger.enable:true}")
    	private Boolean enable;
    
    	@Bean
    	public Docket api() { 
    		return new Docket(DocumentationType.OAS_30)
    					   //资源
    				       .globalResponses(HttpMethod.GET, new ArrayList<>())
    				       .globalResponses(HttpMethod.PUT, new ArrayList<>())
    				       .globalResponses(HttpMethod.POST, new ArrayList<>())
    				       .globalResponses(HttpMethod.DELETE, new ArrayList<>())
    					   //是否启动
    				       .enable(enable)
    					   //头部信息
    				       .apiInfo(apiInfo())
    				       .select()
    				       /** * RequestHandlerSelectors,配置要扫描接口的方式 * basePackage指定要扫描的包 * any()扫描所有，项目中的所有接口都会被扫描到 * none()不扫描 * withClassAnnotation()扫描类上的注解 * withMethodAnnotation()扫描方法上的注解 */
    				       .apis(RequestHandlerSelectors.any())
    					   //过滤某个路径
    				       .paths(PathSelectors.any())
    				       .build()
    					   //协议
    				       .protocols(newHashSet("https", "http"))
    				       .securitySchemes(securitySchemes())
    				       .securityContexts(securityContexts());
    	}
    
    
    
        //配置Swagger 信息 = ApiInfo
        private ApiInfo apiInfo()
        { 
            return new ApiInfo("小唐的Api文档",
                    "好好看文档",
                    "1.0",
                    "xiaotangstudio.cn",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList<>());
        }
    	/** * 设置接口单独的授权信息 */
    	private List<SecurityScheme> securitySchemes() { 
    		return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "header"));
    	}
    
    	/** * 授权信息全局应用 */
    	private List<SecurityContext> securityContexts() { 
    		return Collections.singletonList(
    				SecurityContext.builder()
    						.securityReferences(
    								Collections.singletonList(new SecurityReference("BASE_TOKEN",
    										new AuthorizationScope[]{ new AuthorizationScope("global", "")}
    								)))
    						//.forPaths(PathSelectors.any())
    						.build()
    		);
    	}
    
    	@SafeVarargs
    	private final <T> Set<T> newHashSet(T... ts) { 
    		if (ts.length > 0) { 
    			return new LinkedHashSet<>(Arrays.asList(ts));
    		}
    		return null;
    	}
    }

### 第二个版本 （要使用ui时推荐用这个） ###

@Configuration
    
    public class SwaggerConfig implements WebMvcConfigurer { 
        //配置了Swagger的Docket的bean实例
        //enable是否启动swagger，如果为False则Swagger不能在浏览器访问
        @Bean
        public Docket docket() { 
            Set<String> set = new HashSet<>();
            set.add("https");
            set.add("http");
            return new Docket(DocumentationType.SWAGGER_2).pathMapping("/")
                    .enable(true)//定义是否开启swagger，false为关闭，可以通过变量控制
                    // 微信关注开发者技术前线：定义是否开启swagger，false为关闭，可以通过变量控制
                    .apiInfo(apiInfo())//将api的元信息设置为包含在json ResourceListing响应中。
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.xiaotang.blog"))
                    //paths()过滤什么路径
                    .paths(PathSelectors.any())
                    .build()
                    .protocols(set)// 支持的通讯协议集合
                    .securitySchemes(securitySchemes())// 授权信息设置，必要的header token等认证信息
                    .securityContexts(securityContexts());// 授权信息全局应用
        }
        //作者信息
        Contact contact = new Contact("小唐","xiaotangstudio.cn","1738743304@qq.com");
    
        //配置Swagger 信息 = ApiInfo
        private ApiInfo apiInfo()
        { 
            return new ApiInfo("小唐的Api文档",
                    "好好看文档",
                    "1.0",
                    "xiaotangstudio.cn",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList<>());
        }
        /** * 设置授权信息 */
        private List<SecurityScheme> securitySchemes()
        { 
           List<ApiKey> result = new ArrayList<>();
           ApiKey apiKey = new ApiKey("Authorization","Authorization" ,"Header" );
           result.add(apiKey);
           return  Collections.singletonList(apiKey);
        }
        /** * 授权信息全局应用 */
        private List<SecurityContext> securityContexts() { 
            return Collections.singletonList(
                    SecurityContext.builder()
                            .securityReferences(Collections.singletonList(new SecurityReference("Authorization", new AuthorizationScope[]{ new AuthorizationScope("global", "Authorization")})))
                            .build()
            );
        }
    
    }

单个微服务 目录结构  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0NjQwODgz_size_16_color_FFFFFF_t_70]

### gateway 的swagger配置 ###

/** * swagger的配置类 * * @author teler */
    @Component
    @Primary
    public class MySwaggerResourcesProvider implements SwaggerResourcesProvider { 
    
        /** * swagger3默认的url后缀 */
        private static final String SWAGGER2URL = "/v3/api-docs"; //要使用ui的话 改成v2 不然会出bug 比如有的地方 没有输入框
        /** * 网关路由 */
        private final RouteLocator routeLocator;
    
        /** * 网关应用名称 */
        @Value("${spring.application.name}")
        private String self;
    
        @Autowired
        public MySwaggerResourcesProvider(RouteLocator routeLocator) { 
            this.routeLocator = routeLocator;
        }
    
        /** * 对于gateway来说这块比较重要 让swagger能找到对应的服务 * * @return */
        @Override
        public List<SwaggerResource> get() { 
            List<SwaggerResource> resources = new ArrayList<>();
            List<String> routeHosts = new ArrayList<>();
            // 获取所有可用的host：serviceId
            routeLocator.getRoutes().filter(route -> route.getUri().getHost() != null)
                    .filter(route -> !self.equals(route.getUri().getHost()))
                    .subscribe(route -> routeHosts.add(route.getUri().getHost()));
    
            // 记录已经添加过的server
            Set<String> dealed = new HashSet<>();
            routeHosts.forEach(instance -> { 
                // 拼接url
                String url = "/" + instance.toLowerCase() + SWAGGER2URL;
                if (!dealed.contains(url)) { 
                    dealed.add(url);
                    SwaggerResource swaggerResource = new SwaggerResource();
                    swaggerResource.setUrl(url);
                    swaggerResource.setName(instance);
                    resources.add(swaggerResource);
                }
            });
            return resources;
        }
    }

gateway 目录结构  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0NjQwODgz_size_16_color_FFFFFF_t_70 1]

### 测试访问 ###

两个访问地址 （都是gateway的ip地址和端口 , 我这里端口80 可以不写）

#### 原始ui： http://localhost/swagger-ui/index.html ####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0NjQwODgz_size_16_color_FFFFFF_t_70 2]

#### 好看一点的ui：http://localhost/doc.html ####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0NjQwODgz_size_16_color_FFFFFF_t_70 3]

### 步骤总结 ###

1、导入依赖  
2、配置每一个微服务的swagger  
3、配置gateway的swagger

### 注意点 ###

1、每一个微服务的swagger 要自测通过  
2、使用ui时 记得把gateway的配置改成v2 不然可能没有输入框 ，每一个微服务推荐使用 第二个版本  
![在这里插入图片描述][2021020601333587.png]

### 完整依赖 ###

#### 父依赖 ####

<properties>
            <junit.version>4.13.1</junit.version>
            <lombok.version>1.18.16</lombok.version>
            <log4j.version>1.2.17</log4j.version>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <maven.compiler.source>1.8</maven.compiler.source>
            <maven.compiler.target>1.8</maven.compiler.target>
        </properties>
        
        
        <dependencyManagement>
            <dependencies>
                
                <dependency>
                    <groupId>org.springframework.cloud</groupId>
                    <artifactId>spring-cloud-dependencies</artifactId>
                    <version>2020.0.0</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
                
                <dependency>
                    <groupId>com.alibaba.cloud</groupId>
                    <artifactId>spring-cloud-alibaba-dependencies</artifactId>
                    <version>2.2.4.RELEASE</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
                
                <dependency>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-dependencies</artifactId>
                    <version>2.4.2</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
                
                
                <dependency>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-starter-jdbc</artifactId>
                </dependency>
                
                <dependency>
                    <groupId>com.alibaba</groupId>
                    <artifactId>druid</artifactId>
                    <version>1.2.4</version>
                </dependency>
                
                <dependency>
                    <groupId>com.baomidou</groupId>
                    <artifactId>mybatis-plus-boot-starter</artifactId>
                    <version>3.4.2</version>
                </dependency>
                
                <dependency>
                    <groupId>com.baomidou</groupId>
                    <artifactId>mybatis-plus-generator</artifactId>
                    <version>3.3.1.tmp</version>
                </dependency>
                
                <dependency>
                    <groupId>org.freemarker</groupId>
                    <artifactId>freemarker</artifactId>
                    <version>2.3.30</version>
                </dependency>
                
                <dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-boot-starter</artifactId>
                    <version>3.0.0</version>
                </dependency>
                
                <dependency>
                    <groupId>org.mybatis.spring.boot</groupId>
                    <artifactId>mybatis-spring-boot-starter</artifactId>
                    <version>2.1.4</version>
                </dependency>
                
                <dependency>
                    <groupId>mysql</groupId>
                    <artifactId>mysql-connector-java</artifactId>
                    <version>8.0.22</version>
                </dependency>
    
                
    
                
                <dependency>
                    <groupId>ch.qos.logback</groupId>
                    <artifactId>logback-core</artifactId>
                    <version>1.2.3</version>
                </dependency>
                
                <dependency>
                    <groupId>junit</groupId>
                    <artifactId>junit</artifactId>
                    <version>${junit.version}</version>
                </dependency>
                
                <dependency>
                    <groupId>org.projectlombok</groupId>
                    <artifactId>lombok</artifactId>
                    <version>${lombok.version}</version>
                </dependency>
                
                <dependency>
                    <groupId>log4j</groupId>
                    <artifactId>log4j</artifactId>
                    <version>${log4j.version}</version>
                </dependency>
                
                <dependency>
                    <groupId>io.jsonwebtoken</groupId>
                    <artifactId>jjwt</artifactId>
                    <version>0.9.1</version>
                </dependency>
                
                <dependency>
                    <groupId>com.github.xiaoymin</groupId>
                    <artifactId>swagger-bootstrap-ui</artifactId>
                    <version>1.9.6</version>
                </dependency>
    
    
                
                <dependency>
                    <groupId>org.springframework.security</groupId>
                    <artifactId>spring-security-jwt</artifactId>
                    <version>1.1.1.RELEASE</version>
                </dependency>
                
                <dependency>
                    <groupId>org.springframework.security.oauth.boot</groupId>
                    <artifactId>spring-security-oauth2-autoconfigure</artifactId>
                    <version>2.4.2</version>
                </dependency>
    
            </dependencies>
    
        </dependencyManagement>
        
        <build>
            <resources>
                <resource>
                    <directory>src/main/java</directory>
                    <includes>
                        <include>**/*.properties</include>
                        <include>**/*.xml</include>
                    </includes>
                    <filtering>false</filtering>
                </resource>
                <resource>
                    <directory>src/main/resources</directory>
                    <includes>
                        <include>**/*.properties</include>
                        <include>**/*.xml</include>
                        <include>**/*.yml</include>
                    </includes>
                    <filtering>false</filtering>
                </resource>
            </resources>
        </build>

#### 单个微服务依赖 ####

<dependencies>
            
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
            </dependency>
            
            <dependency>
                <groupId>com.alibaba</groupId>
                <artifactId>fastjson</artifactId>
                <version>1.2.51</version>
            </dependency>
    
            
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-starter-oauth2</artifactId>
                <version>2.2.4.RELEASE</version>
            </dependency>
            
            <dependency>
                <groupId>org.springframework.security</groupId>
                <artifactId>spring-security-jwt</artifactId>
            </dependency>
    
    
            
            
            
            
            
            
            
    
            
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-data-redis</artifactId>
            </dependency>
            
            <dependency>
                <groupId>com.fasterxml.jackson.core</groupId>
                <artifactId>jackson-databind</artifactId>
            </dependency>
            
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <exclusions>
                    <exclusion>
                        <groupId>org.javassist</groupId>
                        <artifactId>javassist</artifactId>
                    </exclusion>
                </exclusions>
            </dependency>
            
            <dependency>
                <groupId>io.jsonwebtoken</groupId>
                <artifactId>jjwt</artifactId>
            </dependency>
            
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-security</artifactId>
            </dependency>
            
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
            </dependency>
            
            <dependency>
                <groupId>org.freemarker</groupId>
                <artifactId>freemarker</artifactId>
            </dependency>
            
            <dependency>
                <groupId>com.baomidou</groupId>
                <artifactId>mybatis-plus-generator</artifactId>
            </dependency>
            
            <dependency>
                <groupId>com.baomidou</groupId>
                <artifactId>mybatis-plus-boot-starter</artifactId>
            </dependency>
            
            <dependency>
                <groupId>mysql</groupId>
                <artifactId>mysql-connector-java</artifactId>
            </dependency>
            
            <dependency>
                <groupId>com.alibaba</groupId>
                <artifactId>druid</artifactId>
            </dependency>
            
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            </dependency>
            
            <dependency>
                <groupId>log4j</groupId>
                <artifactId>log4j</artifactId>
            </dependency>
            
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-test</artifactId>
                <scope>test</scope>
            </dependency>
    
            
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-devtools</artifactId>
            </dependency>
        </dependencies>

#### gateway依赖 ####

<dependencies>
            
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
            </dependency>
            
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-starter-gateway</artifactId>
            </dependency>
            
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-starter-loadbalancer</artifactId>
            </dependency>
    
            
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-boot-starter</artifactId>
            </dependency>
    
            
            <dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <exclusions>
                    <exclusion>
                        <groupId>org.javassist</groupId>
                        <artifactId>javassist</artifactId>
                    </exclusion>
                </exclusions>
            </dependency>
            
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            </dependency>
        </dependencies>

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0NjQwODgz_size_16_color_FFFFFF_t_70]: /images/20221024/7267ad3c5f1f41cbbf4579a29d2fc397.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0NjQwODgz_size_16_color_FFFFFF_t_70 1]: /images/20221024/082708fa39084b368d94dccd5566e194.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0NjQwODgz_size_16_color_FFFFFF_t_70 2]: /images/20221024/63f53749e29149e58155add62ed9b6e6.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM0NjQwODgz_size_16_color_FFFFFF_t_70 3]: /images/20221024/5e6b4945282d460eb66ea0bc9a013184.png
[2021020601333587.png]: /images/20221024/e75350c8026e48e3a35390b96f1b0762.png