【WEEK14】 【DAY4】Swagger第二部分【中文版】

2024.5.30 Thursday
接上文【WEEK14】 【DAY3】Swagger第一部分【中文版】

16.4.配置扫描接口

构建Docket时通过select()方法配置扫描接口的方式

16.4.1.修改SwaggerConfig.java

16.4.1.1.使用.basePackage()方法指定扫描的包路径

package com.P47.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

import java.util.ArrayList;

@Configuration  //等价于@Component
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的bean实例Docket，以配置Swagger的具体参数
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)  //源码见DocumentationType.classpublic class DocumentationType extends SimplePluginMetadata方法，选择符合当前版本的进行编辑
                .apiInfo(apiInfo()) //public Docket(DocumentationType documentationType)方法点开ApiInfo进入ApiInfo.class
                .select()   //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.P47.controll"))
                .build();
        //点击进入Docket.class可见各类方法源码
    }

    //配置Swagger信息（apiInfo）
    private ApiInfo apiInfo(){

        //防止DEFAULT_CONTACT(名字改成了contact)报错
        Contact contact = new Contact("联系人名字", "联系人访问链接", "联系人邮箱");

        return new ApiInfo("Swagger Api Documentation", //标题
                "Api Documentation 描述", //描述
                "version 1.0",  //版本号
                "http://terms.service.url",  //组织链接
                contact,    //联系人信息
                "Apache 2.0",   //许可
                "http://www.apache.org/licenses/LICENSE-2.0",   //许可链接
                new ArrayList<>() //扩展
        );
    }
}

重启后查看：只剩hello-controller栏

16.4.1.2.其他扫描方式均可在RequestHandlerSelectors.class中查看源码

basePackage(final String basePackage) // 根据包路径扫描接口
any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口

withMethodAnnotation(final Class<? extends Annotation> annotation)  // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withClassAnnotation(final Class<? extends Annotation> annotation)   // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口

16.4.2.仍然是修改SwaggerConfig.java

16.4.2.1.配置接口扫描过滤

添加以下过滤

.paths(PathSelectors.ant("/P47/**"))    //点击path查看初始化private Predicate<String> pathSelector; 这里以.ant()方法为例，只扫描请求以/P47开头的接口

重启后查看：没有显示任何方法

16.4.2.2.其他方法：

此时修改后的完整代码

package com.P47.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

import java.util.ArrayList;

@Configuration  //等价于@Component
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的bean实例Docket，以配置Swagger的具体参数
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)  //源码见DocumentationType.classpublic class DocumentationType extends SimplePluginMetadata方法，选择符合当前版本的进行编辑
                .apiInfo(apiInfo()) //public Docket(DocumentationType documentationType)方法点开ApiInfo进入ApiInfo.class
                .select()   //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  //使用basePackage指定要扫描的包
                .paths(PathSelectors.ant("/P47/**"))    //点击path查看初始化private Predicate<String> pathSelector; 这里以.ant()方法为例，只扫描请求以/P47开头的接口
                .build();
        //点击进入Docket.class可见各类方法源码

        /*RequestHandlerSelectors.方法
        basePackage(final String basePackage) // 根据包路径扫描接口
        any() // 扫描所有，项目中的所有接口都会被扫描到
        none() // 不扫描接口

        withMethodAnnotation(final Class<? extends Annotation> annotation)  // 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
        withClassAnnotation(final Class<? extends Annotation> annotation)   // 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
        */

        /*PathSelectors.方法
        any() // 任何请求都扫描
        none() // 任何请求都不扫描
        regex(final String pathRegex) // 通过正则表达式控制
        ant(final String antPattern) // 通过ant()控制
        */
    }

    //配置Swagger信息（apiInfo）
    private ApiInfo apiInfo(){

        //防止DEFAULT_CONTACT(名字改成了contact)报错
        Contact contact = new Contact("联系人名字", "联系人访问链接", "联系人邮箱");

        return new ApiInfo("Swagger Api Documentation", //标题
                "Api Documentation 描述", //描述
                "version 1.0",  //版本号
                "http://terms.service.url",  //组织链接
                contact,    //联系人信息
                "Apache 2.0",   //许可
                "http://www.apache.org/licenses/LICENSE-2.0",   //许可链接
                new ArrayList<>() //扩展
        );
    }
}

16.5.配置Swagger开关

修改SwaggerConfig.java

16.5.1.修改enable的值关闭使用swagger

@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)  //源码见DocumentationType.classpublic class DocumentationType extends SimplePluginMetadata方法，选择符合当前版本的进行编辑
            .apiInfo(apiInfo()) //public Docket(DocumentationType documentationType)方法点开ApiInfo进入ApiInfo.class
            .enable(false)  //是否启动swagger，false则不能启动，此时访问页面显示：😱 Could not render e, see the console.

            .select()   //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
            //.apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  //使用basePackage指定要扫描的包
            //.paths(PathSelectors.ant("/P47/**"))    //点击path查看初始化private Predicate<String> pathSelector; 这里以.ant()方法为例，只扫描请求以/P47开头的接口
            .build();

}

重启：

16.5.2.动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示

16.5.2.1.修改SwaggerConfig

@Bean
public Docket docket(Environment environment){

    // 设置要显示swagger的环境
    Profiles profiles = Profiles.of("dev", "test");
    // 判断当前是否处于该环境
    // 通过 enable() 接收此参数判断是否要显示
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)  //源码见DocumentationType.classpublic class DocumentationType extends SimplePluginMetadata方法，选择符合当前版本的进行编辑
            .apiInfo(apiInfo()) //public Docket(DocumentationType documentationType)方法点开ApiInfo进入ApiInfo.class
            .enable(flag)  //是否启动swagger，false则不能启动，此时访问页面显示：😱 Could not render e, see the console.

            .select()   //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
            //.apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  //使用basePackage指定要扫描的包
            //.paths(PathSelectors.ant("/P47/**"))    //点击path查看初始化private Predicate<String> pathSelector; 这里以.ant()方法为例，只扫描请求以/P47开头的接口
            .build();

}

此时完整的代码：

package com.P47.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
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;

import java.util.ArrayList;

@Configuration  //等价于@Component
@EnableSwagger2 //开启Swagger2
public class SwaggerConfig {
    //配置了Swagger的bean实例Docket，以配置Swagger的具体参数
    @Bean
    public Docket docket(Environment environment){

        // 设置要显示swagger的环境
        Profiles profiles = Profiles.of("dev", "test");
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)  //源码见DocumentationType.classpublic class DocumentationType extends SimplePluginMetadata方法，选择符合当前版本的进行编辑
                .apiInfo(apiInfo()) //public Docket(DocumentationType documentationType)方法点开ApiInfo进入ApiInfo.class
                .enable(flag)  //是否启动swagger，false则不能启动，此时访问页面显示：😱 Could not render e, see the console.

                .select()   //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                //.apis(RequestHandlerSelectors.basePackage("com.P47.controll"))  //使用basePackage指定要扫描的包
                //.paths(PathSelectors.ant("/P47/**"))    //点击path查看初始化private Predicate<String> pathSelector; 这里以.ant()方法为例，只扫描请求以/P47开头的接口
                .build();

    }

    //配置Swagger信息（apiInfo）
    private ApiInfo apiInfo(){

        //防止DEFAULT_CONTACT(名字改成了contact)报错
        Contact contact = new Contact("联系人名字", "联系人访问链接", "联系人邮箱");

        return new ApiInfo("Swagger Api Documentation", //标题
                "Api Documentation 描述", //描述
                "version 1.0",  //版本号
                "http://terms.service.url",  //组织链接
                contact,    //联系人信息
                "Apache 2.0",   //许可
                "http://www.apache.org/licenses/LICENSE-2.0",   //许可链接
                new ArrayList<>() //扩展
        );
    }
}

16.5.2.2.修改application.properties

spring.application.name=swagger-demo
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
spring.profiles.active=dev

16.5.2.3.新建application-dev.properties

#生产环境
server.port=8081

16.5.2.4.新建application-pro.properties

#测试环境
server.port=8082

16.5.2.5.重启

访问http://localhost:8081/swagger-ui.html

将application.properties中配置改为spring.profiles.active=pro，访问http://localhost:8082/swagger-ui.html无法进入swagger页面。

同理，如果不写spring.profiles.active指定文件，默认端口是8080，由于此时在SwaggerConfig中的配置，http://localhost:8080/swagger-ui.html也不可访问swagger。