SpringCloud Zuul网关整合Swagger

╰半橙微兮° 2022-04-11 04:19 267阅读 0赞

# 一、关于Swagger #

**Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：**

*  Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
 *  Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
 *  Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
 *  Swagger 有一个强大的社区，里面有许多强悍的贡献者

--------------------

# 二、该篇博客使用技术版本 #

springcloud：Dalston.SR5

springboot：1.5.9.RELEASE

springfox-swagger-ui：2.7.0

pringfox-swagger2：2.7.0

zuul-core：1.3.0

--------------------

# 三、开发实现 #

## 1、在总依赖中添加swagger相关依赖(因为多处地方会使用) ##

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.7.0</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.7.0</version>
    </dependency>

## 2、在网关服务下创建swagger ##

首先网关路由先配置好，如下

zuul:
      host:
        connect-timeout-millis: 3000
        socket-timeout-millis: 3000
      #路由规则
      routes:
        api-user:
          path: /api/user/**
          serviceId: wc-client-user
          #防止网关转发请求后session失效
          sensitiveHeaders: "*"
        api-search:
          path: /api/search/**
          serviceId: wc-client-search
          sensitiveHeaders: "*"

这里主要创建DocumentationConfig和SwaggerConfig，目录如下

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dfbGludXg_size_16_color_FFFFFF_t_70][]

> DocumentationConfig.java

/**
     * 资源文档配置类
     */
    @Component
    @Primary
    public class DocumentationConfig implements SwaggerResourcesProvider{
    
        @Override
        public List<SwaggerResource> get() {
            List resources = new ArrayList<>();
            resources.add(swaggerResource("搜索服务接口", "/api/search/v2/api-docs", "1.0"));// /api/search/是网关路由，/v2/api-docs是swagger中的
            resources.add(swaggerResource("用户服务接口", "/api/user/v2/api-docs", "1.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;
        }
    
    }

> SwaggerConfig.java

/**
     * swagger配置
     */
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("WingCloud")
                    .description("WingCloud")
                    .termsOfServiceUrl("http://localhost:8080")//网关端口
                    .version("1.0")
                    .build();
        }
    
        @Bean
        UiConfiguration uiConfig() {
            return new UiConfiguration(null, "list", "alpha", "schema",
                    UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L);
        }
    
    }

## 3、在网关启动类上加上@EnableSwagger2注解 ##

## 4、在client服务内的controller中进行注明 ##

笔者这里以user服务为例

如下在类上添加@Api，在方法上添加@ApiOperation，当然还有其他注解，读者可自行百度/谷歌

/**
     * 用户请求处理控制器
     */
    @Api("用户管理接口")
    @RestController
    public class UserController extends BaseController {
    
        @Autowired
        private IUserService userService;
    
        /**
         * 用户登录
         * @param request
         * @param result
         * @param req
         * @return
         */
        @ApiOperation(value = "/login",notes = "登录接口")
        @RequestMapping("/login")
        public SingleResult<TokenResponse> login(@Valid @RequestBody LoginRequest request, BindingResult result,HttpServletRequest req){
            //必须要调用validate方法才能实现输入参数的合法性校验
            System.out.println("-------------test-----------");
            validate(result);
            return userService.login(request,req);
        }
    }

## 5、在client服务中添加Swagger配置 ##

如下图目录

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dfbGludXg_size_16_color_FFFFFF_t_70 1][]

> SwaggerConfig.java

/**
     * swagger配置
     */
    @EnableSwagger2
    @Configuration
    public class SwaggerConfig {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("top.wingcloud.controller"))//过滤的路径
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("wc-client-user")
                    .description("接口文档说明")
                    .contact(new Contact("浅然", "", "xulinjie0105@gmail.com"))
                    .version("2.0")
                    .build();
        }
    }

ok，配置整合完成后，启动相应的服务，然后进入[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]即可看到如下界面

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dfbGludXg_size_16_color_FFFFFF_t_70 2][]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dfbGludXg_size_16_color_FFFFFF_t_70]: /images/20220411/6f7fe65e61434dbd9b66fd70aaf7dbf2.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dfbGludXg_size_16_color_FFFFFF_t_70 1]: /images/20220411/9243eae8e2a24b6489b0f73207765aff.png
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dfbGludXg_size_16_color_FFFFFF_t_70 2]: /images/20220411/4fdbbe8e880d4c389d90d386d0aa2f3d.png