系列学习 Swagger 之第 2 篇 —— SpringCloud Gateway 整合 Swagger(完结)
作者:互联网
OK,这一篇博客继续讲解 Swagger 整合到 SpringCloud Gateway。
我们使用 swagger-spring-boot-starter 版本,可以查看 Maven 官网:https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter
我们搭建一个完整的 demo,包括注册中心 Eureka(端口8080),网关 Gateway(端口80),2个微服务:产品微服务(端口1001)、订单微服务(端口1002)。代码结构如图:
这里只说重点部分,可以先下载代码:https://pan.baidu.com/s/17XKJEwNLpcxf-7PtmbOU_Q 提取码:f7b3
最外层 pom.xml 配置如下:
<?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.study</groupId>
<artifactId>swagger-gateway</artifactId>
<packaging>pom</packaging>
<version>1.0-SNAPSHOT</version>
<modules>
<module>eureka-server</module>
<module>gateway-server</module>
<module>product-server</module>
<module>order-server</module>
</modules>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.2.2.RELEASE</version>
</parent>
<properties>
<!-- 配置 Swagger 版本 -->
<swagger.version>1.9.0.RELEASE</swagger.version>
</properties>
<dependencies>
<!--Spring boot 集成包-->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!-- swagger-start 依赖。https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter -->
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>${swagger.version}</version>
</dependency>
<!-- lombok 依赖 -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Hoxton.SR2</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
</project>
然后说一下产品服务的代码,订单服务是一样的,不赘述。
product-server 的 pom.xml 配置:
<?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">
<parent>
<artifactId>swagger-gateway</artifactId>
<groupId>com.study</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>product-server</artifactId>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
</project>
实体类:
package com.study.entity;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.*;
/**
* @author biandan
* @description
* @signature 让天下没有难写的代码
* @create 2021-06-06 下午 5:45
*/
@Data
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor(staticName = "of")
@Builder
@ApiModel(description = "产品实体类")
public class ProductEntity {
@ApiModelProperty(value = "产品ID")
private Integer productId;
@ApiModelProperty(value = "产品名称")
private String productName;
}
控制层:只需要添加注解 @EnableSwagger2Doc 即可,因为 SpringBoot 已经帮我们整合配置了,不需要 SwaggerConfig 类!
package com.study.controller;
import com.spring4all.swagger.EnableSwagger2Doc;
import com.study.entity.ProductEntity;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* @author biandan
* @description
* @signature 让天下没有难写的代码
* @create 2021-06-06 下午 5:45
*/
@RestController
@Api(tags = "产品信息管理 API 接口文档")
@RequestMapping("/api/product")
@EnableSwagger2Doc //SpringBoot 已经整合好 swagger 的相关配置了
public class ProductController {
@PostMapping("/getProductInfo")
@ApiOperation(value = "查询产品信息接口", notes = "这是一段方法的描述")
@ApiImplicitParams({
@ApiImplicitParam(name = "productId", value = "产品Id", required = false, dataType = "Integer"),
@ApiImplicitParam(name = "productName", value = "产品名称", required = true, dataType = "String")
})
public ProductEntity getInfo(@RequestParam(value = "productId",required = false) Integer productId,
@RequestParam("productName") String productName) {
ProductEntity productEntity = new ProductEntity();
productEntity.setProductId(123);
productEntity.setProductName("霸王防脱洗发液");
return productEntity;
}
}
如果想自定义配置信息,怎么办?可以自定义配置类 SwaggerConfig,也可以写在配置文件里,如下:
application.yml 代码
server:
port: 1001
eureka:
instance:
hostname: 127.0.0.1
client:
serviceUrl:
defaultZone: http://${eureka.instance.hostname}:8080/eureka/
spring:
application:
name: product-server
# swagger 相关配置
swagger:
title: "无限商城-产品模块"
description: "让天下没有难写的代码"
version: V1.0
enabled: true
然后到网关服务的代码
pom.xml 配置
<?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">
<parent>
<artifactId>swagger-gateway</artifactId>
<groupId>com.study</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>gateway-server</artifactId>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
</dependencies>
</project>
配置类 SwaggerConfig,需要实现接口:springfox.documentation.swagger.web.SwaggerResourcesProvider
package com.study.config;
import lombok.AllArgsConstructor;
import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;
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;
/**
* @author biandan
* @description
* @signature 让天下没有难写的代码
* @create 2021-06-07 上午 1:29
*/
@Component
@Primary
@AllArgsConstructor
public class SwaggerConfig implements SwaggerResourcesProvider {
public static final String API_URI = "/v2/api-docs";
private final RouteLocator routeLocator;
private final GatewayProperties gatewayProperties;
@Override
public List<SwaggerResource> get() {
List<SwaggerResource> resources = new ArrayList<>();
List<String> routes = new ArrayList<>();
//取出gateway的route
routeLocator.getRoutes().subscribe(route -> routes.add(route.getId()));
//结合配置的route-路径(Path),和route过滤,只获取有效的route节点
gatewayProperties.getRoutes().stream().filter(routeDefinition -> routes.contains(routeDefinition.getId()))
.forEach(routeDefinition -> routeDefinition.getPredicates().stream()
.filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
.forEach(predicateDefinition -> resources.add(swaggerResource(routeDefinition.getId(),
"/"+routeDefinition.getId()+API_URI ))));
return resources;
}
private SwaggerResource swaggerResource(String name, String location) {
SwaggerResource swaggerResource = new SwaggerResource();
swaggerResource.setName(name);
swaggerResource.setLocation(location);
swaggerResource.setSwaggerVersion("2.0");
return swaggerResource;
}
}
控制层 controller
package com.study.controller;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;
import springfox.documentation.swagger.web.*;
import java.util.Optional;
/**
* @author biandan
* @description
* @signature 让天下没有难写的代码
* @create 2021-06-07 上午 1:31
*/
@RestController
@RequestMapping("/swagger-resources")
public class SwaggerController {
@Autowired(required = false)
private SecurityConfiguration securityConfiguration;
@Autowired(required = false)
private UiConfiguration uiConfiguration;
private final SwaggerResourcesProvider swaggerResources;
@Autowired
public SwaggerController(SwaggerResourcesProvider swaggerResources) {
this.swaggerResources = swaggerResources;
}
@GetMapping("/configuration/security")
public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
}
@GetMapping("/configuration/ui")
public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
return Mono.just(new ResponseEntity<>(
Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
}
@GetMapping("")
public Mono<ResponseEntity> swaggerResources() {
return Mono.just((new ResponseEntity<>(swaggerResources.get(), HttpStatus.OK)));
}
}
重点来了,application.yml 配置
server:
port: 80
eureka:
instance:
hostname: 127.0.0.1
client:
serviceUrl:
defaultZone: http://${eureka.instance.hostname}:8080/eureka/
spring:
application:
name: gateway-server
cloud:
gateway:
discovery:
locator:
enabled: true #表明gateway开启服务注册和发现的功能, 动态路由
lowerCaseServiceId: true
routes:
# 路由的 ID,没有固定规则但要求唯一,建议配合服务名
# 产品微服务路由
- id: product-server
# 根据服务名称从注册中心获取服务地址
uri: lb://product-server
# 断言
predicates:
- Path=/**
# 产品微服务路由
- id: order-server
# 根据服务名称从注册中心获取服务地址
uri: lb://order-server
# 断言
predicates:
- Path=/**
说明:
1、配置动态路由,否则会报错:Failed to load API definition. 找不到 API 的定义
2、为每个微服务配置路由规则 routes,否则报错:
标签:swagger,SpringCloud,springframework,server,import,系列学习,org,Swagger,com 来源: https://blog.csdn.net/BiandanLoveyou/article/details/117638887