三Swagger配置

Posted 2021-05-20 上善若水

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了三Swagger配置相关的知识，希望对你有一定的参考价值。

一、swagger配置

可以在项目中创建SwaggerConfig，进行配置文档内容。

1.1、配置基本信息

Docket：摘要对象，通过对象配置描述文件的信息。
apiInfo：设置描述文件中info。参数类型ApiInfo。
select()：返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象。
ApiInfoBuilder：ApiInfo构建器。

package com.xbmu.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfiguration
{
    /**
     * 创建docket类型的对象。并使用spring容器管理。
     * docket是swagger中的全局配置对象。
     * @return
     */
    @Bean
    public Docket docket()
    {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);

        // API 帮助文档的描述信息。information
        ApiInfo apiInfo = new ApiInfoBuilder().contact(
                    // 配置swagger文档主体内容。
                    new Contact(
                            "swagger2接口文档学习 - 毕涛涛", // 是文档的发布者名称
                            "https://blog.csdn.net/btt2013", // 是文档发布者的网站地址。
                            "btt2015@163.com" //文档发布者的电子邮箱
                    )
                ).title("swagger框架学习帮助文档")
                .description("swagger框架学习帮助文档详细描述--swagger框架是一个用于开发RestAPI帮助文档")
                .version("1.1")
                .build();
        // 给docket上下文配置api描述信息
        docket.apiInfo(apiInfo);
        return docket;
    }
}

在这里插入图片描述

1.2、设置扫描的包

可以通过apis()方法设置哪个包中内容被扫描

package com.xbmu.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
@Configuration
public class SwaggerConfiguration
{
    /**
     * 创建docket类型的对象。并使用spring容器管理。
     * docket是swagger中的全局配置对象。
     * @return
     */
    @Bean
    public Docket docket()
    {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);

        // API 帮助文档的描述信息。information
        ApiInfo apiInfo = new ApiInfoBuilder().contact(
                    // 配置swagger文档主体内容。
                    new Contact(
                            "swagger2接口文档学习 - 毕涛涛", // 是文档的发布者名称
                            "https://blog.csdn.net/btt2013", // 是文档发布者的网站地址。
                            "btt2015@163.com" //文档发布者的电子邮箱
                    )
                ).title("swagger框架学习帮助文档")
                .description("swagger框架学习帮助文档详细描述--swagger框架是一个用于开发RestAPI帮助文档")
                .version("1.1")
                .build();
        // 给docket上下文配置api描述信息
        docket.apiInfo(apiInfo);

        docket
                .select() // 获取docket中的选择器。返回ApiSelectorBuilder。构建选择器，如：扫描什么包的注解。
                .apis(RequestHandlerSelectors.basePackage("com.xbmu.controller")).build();// 设定扫描那个包(包含子包)
        return docket;
    }
}

1.3、自定义注解设置不需要生成接口文档的方法

1.3.1 自定义注解

注解名称随意。

package com.xbmu.anno;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 *  @Target - 描述当前的注解可以定义在什么资源上。
 *  属性 value
 *   - 定义具体的资源。包括：
 *   - ElementType.METHOD 可以定义在方法上
 *   - ElementType.TYPE   可以定义在类型上
 *   - ElementType.FIELD  可以定义在属性上
 *   - ElementType.PARAMETER 可以定义在方法参数上
 * @Retention - 当前注解在什么时候有效
 *  属性 value
 *   - 定义具体的生效标记
 *   - RetentionPolicy.RUNTIME  运行时有效
 *   - RetentionPolicy.SOURCE   源码中有效
 *   - RetentionPolicy.CLASS    字节码有效
 *
 */
@Target(value = {ElementType.METHOD,ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger {
}

1.3.2 添加规则

通过 public ApiSelectorBuilder apis(Predicate selector) 可以设置生成规则。
public static Predicate not(Predicate predicate) ：表示不允许的条件。
withMethodAnnotation：表示此注解是方法级别注解。

package com.xbmu.config;

import com.google.common.base.Predicates;
import com.xbmu.anno.NotIncludeSwagger;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
@Configuration
public class SwaggerConfiguration
{
    /**
     * 创建docket类型的对象。并使用spring容器管理。
     * docket是swagger中的全局配置对象。
     * @return
     */
    @Bean
    public Docket docket()
    {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);

        // API 帮助文档的描述信息。information
        ApiInfo apiInfo = new ApiInfoBuilder().contact(
                    // 配置swagger文档主体内容。
                    new Contact(
                            "swagger2接口文档学习 - 毕涛涛", // 是文档的发布者名称
                            "https://blog.csdn.net/btt2013", // 是文档发布者的网站地址。
                            "btt2015@163.com" //文档发布者的电子邮箱
                    )
                ).title("swagger框架学习帮助文档")
                .description("swagger框架学习帮助文档详细描述--swagger框架是一个用于开发RestAPI帮助文档")
                .version("1.1")
                .build();
        // 给docket上下文配置api描述信息
        docket.apiInfo(apiInfo);

        docket
                .select() // 获取docket中的选择器。返回ApiSelectorBuilder。构建选择器，如：扫描什么包的注解。
                .apis(Predicates.not( // 取反。false -> true  true -> false
                        RequestHandlerSelectors.withMethodAnnotation(// 当方法上有注解的时，返回true
                                NotIncludeSwagger.class
                        ) // 方法上有该注解的时候返回true
                )).build();
                //.apis(RequestHandlerSelectors.basePackage("com.xbmu.controller")).build();// 设定扫描那个包(包含子包)
        return docket;
    }
}

1.3.3 添加NotIncludeSwagger注解

在不需要生成接口文档的方法上面添加@NotIncludeSwagger注解后，该方法将不会被swagger进行生成在接口文档中。

    @NotIncludeSwagger
    @RequestMapping("/req")
    public String req(String param1)
    {
        return "req";
    }

1.4、设置范围

通过public ApiSelectorBuilder paths(Predicate selector)可以设置满足什么样规则的url被生成接口文档。可以使用正则表达式进行匹配。
下面例子中表示只有以/demo/开头的url才能被swagger生成接口文档。
如果希望全部扫描可以使用 paths(PathSelectors.any())

package com.xbmu.config;

import com.google.common.base.Predicates;
import com.xbmu.anno.NotIncludeSwagger;
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;
@Configuration
public class SwaggerConfiguration
{
    /**
     * 创建docket类型的对象。并使用spring容器管理。
     * docket是swagger中的全局配置对象。
     * @return
     */
    @Bean
    public Docket docket()
    {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);

        // API 帮助文档的描述信息。information
        ApiInfo apiInfo = new ApiInfoBuilder().contact(
                    // 配置swagger文档主体内容。
                    new Contact(
                            "swagger2接口文档学习 - 毕涛涛", // 是文档的发布者名称
                            "https://blog.csdn.net/btt2013", // 是文档发布者的网站地址。
                            "btt2015@163.com" //文档发布者的电子邮箱
                    )
                ).title("swagger框架学习帮助文档")
                .description("swagger框架学习帮助文档详细描述--swagger框架是一个用于开发RestAPI帮助文档")
                .version("1.1")
                .build();
        // 给docket上下文配置api描述信息
        docket.apiInfo(apiInfo);

        docket
                .select() // 获取docket中的选择器。返回ApiSelectorBuilder。构建选择器，如：扫描什么包的注解。
                .apis(Predicates.not( // 取反。false -> true  true -> false
                        RequestHandlerSelectors.withMethodAnnotation(// 当方法上有注解的时，返回true
                                NotIncludeSwagger.class
                        ) // 方法上有该注解的时候返回true
                ))
                .apis(RequestHandlerSelectors.basePackage("com.xbmu.controller"))
                .paths(Predicates.or( // 多个规则符合任意一个即可通过。
                        PathSelectors.regex("/person/.*"),// 使用正则表达式，约束生成API文档的路径地址。
                        PathSelectors.regex("/person2/.*"),
                        PathSelectors.regex("/.*")
                ))
                .build();// 设定扫描那个包(包含子包)
        return docket;
    }
}

以上是关于三Swagger配置的主要内容，如果未能解决你的问题，请参考以下文章

springboot项目配置swagger2示例

Springboot系列集成接口文档swagger，使用，测试

swagger 基础入门

配置 VScode 编辑器 (前端篇)

springboot+jpa+mysql+redis+swagger整合步骤