swagger系列教程二

朴灿烈づ我的快乐病毒、 2024-04-19 13:03 61阅读 0赞

项目源码地址：https://github.com/Dr-Water/fast-json-test  
springfox默认会把所有api分成一组，这样通过类似于http://127.0.0.1:8080/jadDemo/swagger-ui.html这样的地址访问时，会在同一个页面里加载所有api列表。这样，如果系统稍大一点，api稍微多一点，页面就会出现假死的情况，所以很有必要对api进行分组。api分组，是通过在ApiConf这个配置文件中，通过@Bean注解定义一些Docket实例，网上常见的配置如下:

@EnableSwagger2
    publicclass ApiConfig { 
    @Bean
     public Docket customDocket() { 
           return newDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
        }
    }

上述代码中通过@Bean注入一个Docket，这个配置并不是必须的，如果没有这个配置，框架会自己生成一个默认的Docket实例。这个Docket实例的作用就是指定所有它能管理的api的公共信息，比如api版本、作者等等基本信息，以及指定只列出哪些api（通过api地址或注解过滤）。

Docket实例可以有多个，比如如下代码：

package com.ratel.json.config;
    
    import io.swagger.annotations.ApiOperation;
    import org.springframework.beans.factory.annotation.Value;
    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.ApiKey;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.List;
    
    import static com.google.common.collect.Lists.newArrayList;
    
    /** * @业务描述： * @package_name： com.ratel.json.config * @project_name： fast-json-test * @author： ratelfu@qq.com * @create_time： 2019-09-17 17:27 * @copyright (c) ratelfu 版权所有 */
    
    @Configuration
    @EnableSwagger2
    public class Swagger2GroupConfig { 
    
    
        /** * 是否开启swagger，正式环境一般是需要关闭的 ，使用@value注解从application.yml中获取属性 */
        @Value("${swagger.enabled}")
        private boolean enableSwagger;
        @Bean
        public Docket createRestApiGroup1() { 
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("apiGroup1")
                    .apiInfo(apiInfo())
                    //是否开启 (true 开启 false隐藏。生产环境建议隐藏)
                    .enable(enableSwagger)
                    .select()
                    //加了ApiOperation注解的类，才生成接口文档
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    //包下的类，才生成接口文档
                    //.apis(RequestHandlerSelectors.basePackage("com.ratel.controller"))
                    .paths(PathSelectors.ant("/user/**"))
                    .build()
                    .securitySchemes(security());
        }
    
        @Bean
        public Docket createRestApiGroup2() { 
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("apiGroup2")
                    .apiInfo(apiInfo())
                    //是否开启 (true 开启 false隐藏。生产环境建议隐藏)
                    .enable(enableSwagger)
                    .select()
                    //加了ApiOperation注解的类，才生成接口文档
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    //包下的类，才生成接口文档
                    //.apis(RequestHandlerSelectors.basePackage("com.ratel.controller"))
                    .paths(PathSelectors.ant("/shop/**"))
                    .build()
                    .securitySchemes(security());
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2构建RESTful APIs")
                    .description("更多Spring Boot相关文章请关注：https://blog.csdn.net/weter_drop")
                    .termsOfServiceUrl("https://blog.csdn.net/weter_drop/")
                    .contact("ratel")
                    .version("1.0")
                    .build();
        }
    
        /** *添加swagger的安全相关的参数，比如在请求头中添加 token * @return */
        private List<ApiKey> security() { 
            return newArrayList(
                    new ApiKey("token", "token", "header")
            );
        }
    
    }

当在项目中配置了多个Docket实例时，也就可以对api进行分组了，比如上面代码将api分为了两组。在这种情况下，必须给每一组指定一个不同的名称，比如上面代码中的"apiGroup1"和"apiGroup2"，每一组可以用paths通过ant风格的地址表达式来指定哪一组管理哪些api。比如上面配置中，第一组管理地址为/user/开头的api第二组管理/shop/开头的api。当然，还有很多其它的过滤方式，比如跟据类注解、方法注解、地址正则表达式等等。分组后，在api 列表界面右上角的下拉选项中就可以选择不同的api组。这样就把项目的api列表分散到不同的页面了。这样，即方便管理，又不致于页面因需要加载太多api而假死。

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

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dldGVyX2Ryb3A_size_16_color_FFFFFF_t_70]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/18/58cfbb7c978a4c76a5cc1bf9e1fae9ce.png