Spring Cloud Gateway 整合 Swagger2

最新推荐文章于 2024-07-16 21:14:11 发布

OZGxin

最新推荐文章于 2024-07-16 21:14:11 发布

阅读量1.4k

点赞数 1

分类专栏： Spring Cloud2.0 文章标签：后端 spring boot

本文链接：https://blog.youkuaiyun.com/qq_37282260/article/details/104757486

版权

Spring Cloud2.0 专栏收录该内容

1 篇文章

订阅专栏

本文详细介绍如何在SpringCloud Gateway中整合Swagger2，实现微服务API文档的统一管理和展示。从添加依赖、配置Swagger资源提供者到实现Swagger UI的自定义处理，再到业务模块的Swagger配置，一步步引导读者完成整个过程。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

Spring Cloud Gateway 整合Swagger2 （微服务API文档）

前提是spring-boot-starter-parent版本为2.1.3.RELEASE

1.创建Gateway module项目，添加maven依赖

<!--gateway 网关依赖,内置webflux 依赖-->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis-reactive</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-gateway-core</artifactId>
    <version>2.1.0.RELEASE</version>
</dependency>

2. 在Gateway module项目下创建config （package）包，添加SwaggerProvider文件

import lombok.AllArgsConstructor;
import org.springframework.cloud.gateway.support.NameUtils;
import org.springframework.context.annotation.Primary;
import org.springframework.stereotype.Component;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;
import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;

import java.util.ArrayList;
import java.util.List;



/**
 * @ClassName: SwaggerProvider
 * @Description: 聚合接口文档注册
 * @Author Gxin
 * @Date 2020/3/9 17:03
 * @Version： 1.0
**/
@Component
@Primary
@AllArgsConstructor
public class SwaggerProvider 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(),
                        predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
                              .replace("/**", 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;
   }
}

3. 创建handler包，添加SwaggerHandler文件

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;

@RestController
@RequestMapping("/swagger-resources")
public class SwaggerHandler {
    @Autowired(required = false)
    private SecurityConfiguration securityConfiguration;
    @Autowired(required = false)
    private UiConfiguration uiConfiguration;
    private final SwaggerResourcesProvider swaggerResources;

    @Autowired
    public SwaggerHandler(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)));
    }
}

4. 在resources下添加application.yml

server:
  port: 8861
spring:
  application:
    name: @artifactId@
  cloud:
    gateway:
      discovery:
        locator:
# Gateway开启服务注册和发现功能
          enabled: true
# 将请求路径上的服务名配置为小写
          lowerCaseServiceId: true
      routes:
        - id: ozx-shop-service-weixin                     #网关路由
          uri: lb://OZX-SHOP-SERVICE-WEIXIN
          predicates:
            - Path=/wx/**
#  StripPrefix的filter在转发之前将/wx去掉
          filters:
            - StripPrefix=1
#            - SwaggerHeaderFilter
        - id: ozx-shop-service-member
          uri: lb://OZX-SHOP-SERVICE-MEMBER
          predicates:
            - Path=/mem/**
          #  StripPrefix的filter在转发之前将/mem去掉
          filters:
            - StripPrefix=1

eureka:
  instance:
    prefer-ip-address: true
  client:
    service-url:
      defaultZone: http://127.0.0.1:8761/eureka/

5.在业务module添加swagger2 maven 依赖

<dependency><!--添加Swagger依赖 -->
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<dependency><!--添加Swagger-UI依赖 -->
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>
<!--添加以下配置，java.lang.NumberFormatException: For input string: ""
解决Swagger2.9.2的NumberFormatException问题-->
<dependency>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-annotations</artifactId>
   <version>1.5.22</version>
</dependency>
<dependency>
   <groupId>io.swagger</groupId>
   <artifactId>swagger-models</artifactId>
   <version>1.5.22</version>
</dependency>

6. 在业务module 添加SwaggerConfig文件

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @ClassName: SwaggerConfig
 * @Description: 以yml文件配置方式配置swagger，类配置swagger属性已弃用
 * @Author Gxin
 * @Date 2020/1/9 16:32
 * @Version： 1.0
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi(){
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                    .apis(RequestHandlerSelectors.basePackage("swagger相关注解所在的包路径"))
                    .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Swagger API")
                    .description("接口文档")
                        .termsOfServiceUrl("团队网站")
                            .contact(new Contact("作者名","","电子邮箱"))
                                .version("版本号")
                                    .build();
    }
}

7. 以application.yml文件配置swagger网页参数

swagger:
  base-package: com.ozx.ozxshopservicemember.controller #swagger相关注解所在的包路径
  title: SpringBoot2.x构建集成swagger2项目
  description: API文档自动生成
  version: 1.1
  terms-of-service-url: https://github.com/OGxin
  contact:
    name: Gxin
    email: 电子邮箱
    url: https://github.com/OGxin

8. 添加Controller

package com.ozx.ozxshopservicemember.controller;
import com.alibaba.fastjson.JSONObject;
import com.ozx.ozxshopapimemberdto.input.UserInpDTO;
import com.ozx.ozxshopcommon.basic.BasicResponse;
import com.ozx.ozxshopserviceapimember.service.UserRegisterService;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @ClassName: UserResigterController
 * @Description: 用户注册模块
 * @Author Gxin
 * @Date 2020/3/9 15:15
 * @Version： 1.0
 **/
@RestController
@RequestMapping("/mem")
@ApiModel("用户注册模块")
public class UserResigterController {
    @Autowired
    private UserRegisterService userRegisterService;

    @PostMapping("/reg")
    @ApiOperation(value = "注册",notes = "注册接口")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "regCode",paramType = "query",value = "验证码",dataType = "String",example = "12345")
    }
    )
    public BasicResponse<JSONObject> register(UserInpDTO userInpDTO,String regCode){
        return userRegisterService.register(userInpDTO, regCode);
    }
}