swagger系列教程二

这是我参与11月更文挑战的第27天，活动详情查看：2021最后一次更文挑战

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： [email protected]
 * @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而假死。

在这里插入图片描述

猜你喜欢