Swagger

Posted 2023-04-07 liu-jin

1.添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

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

2.配置config类，在启动类上配置@EnableSwagger2

@Configuration
public class SwaggerConfig 
    @Bean
    public Docket docket(Environment environment) 
        //生产环境和正式环境，正式环境不可以显示
        //设置环境为正式环境
        Profiles profiles = Profiles.of("dev");
        //判断当前环境是否处于自己设置的环境当中
        boolean flag = environment.acceptsProfiles(profiles);
        Docket docket = new Docket(DocumentationType.SWAGGER_2);

        //作者信息
        Contact contact = new Contact("liujin", "https://liu.com", "[e-mail]");

        //Swagger配置信息
        ApiInfo apiInfo = new ApiInfo("开发者文档",
                "前后端分离",
                "v1.0",
                "http://bigshop.com", contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
        docket.apiInfo(apiInfo)
                .enable(flag)//如果值为false，则不能在浏览器中访问swagger，默认为true
                .select()
                .apis(RequestHandlerSelectors
                //RequestHandlerSelectors;配置要扫描接口的方式
                //basePackage;指定要扫描的包（一般使用的都是这个）
                //any();扫描全部
                //none();不扫描
                //withClassAnnotation:扫描的是类上的注解
                //withMethodAnotation;扫描的是方法上的注解

                .basePackage("com.liujin.controller"))
                //paths（）过滤什么路径，比如在上面controller包下继续过滤带。。。。的接口
                //一般使用的是ant方法
                .paths(PathSelectors.ant("/liu/**"))
                .build();
        return docket;

    

3.配置注解@Api开头

@ApiModel("用户实体类")
public class User 
    @ApiModelProperty("用户名")
   private String username;
    @ApiModelProperty("密码")
   private String password;

RestController
@RequestMapping("/user")
public class UserController 
    @PutMapping
    //@ApiOperation方法的注解
    @ApiOperation("添加user")
    //@ApiParam是参数的注解
    public String addUser(@ApiParam("用户信息") User user)
        return "测试";
    

Swagger--配置扫描接口及开关

01: Swagger–介绍及SpringBoot集成Swagger
02: Swagger–配置Swagger信息
03: Swagger–配置扫描接口及开关
04: Swagger–分组 & 接口注释
05: Swagger–接口测试&Swagger小结

1. Swagger--配置扫描接口及开关

---

1.1 配置扫描接口

SwaggerConfig.java

    /**
     * 配置docket以配置Swagger具体参数
     */
    @Bean
    public Docket docket() {
        /*
         * 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
         * basePackage(final String basePackage) // 根据包路径扫描接口（最常用）
         * any() 扫描所有，项目中的所有接口都会被扫描到
         * none() 不扫描接口
         * 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
         * withMethodAnnotation(final Class<? extends Annotation> annotation)
         * 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
         * withClassAnnotation(final Class<? extends Annotation> annotation)
         */
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.tian.swagger.controller")).build();
    }

运行结果（因为现在只扫描了com.tian.swagger.controller 的包 所以只会有一个HelloController）：

---

1.2 配置接口扫描过滤

SwaggerConfig.java

    /**
     * 配置docket以配置Swagger具体参数
     */
    @Bean
    public Docket docket() {
        /*
         * 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
         * basePackage(final String basePackage) // 根据包路径扫描接口
         * any() 扫描所有，项目中的所有接口都会被扫描到
         * none() 不扫描接口
         * 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
         * withMethodAnnotation(final Class<? extends Annotation> annotation)
         * 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
         * withClassAnnotation(final Class<? extends Annotation> annotation)
         */
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.tian.swagger.controller")).paths(PathSelectors.ant("/tian/**")).build();
    }

这里只选择了请求路径包含了/tian下的所有接口

这里可以选择的参数有：

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

---

1.3 配置Swagger开关

enable(boolean) 表示是否启用Swagger 默认为true(启用) 如果为false,则Swagger不能在游览器中访问

SwaggerConfig.java

    /**
     * 配置docket以配置Swagger具体参数
     */
    @Bean
    public Docket docket() {
        // enable(boolean) 表示是否启用Swagger 默认为true(启用) 如果为false,则Swagger不能在游览器中访问
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(false).select().apis(RequestHandlerSelectors.basePackage("com.tian.swagger.controller")).paths(PathSelectors.ant("/tian/**")).build();
    }

运行结果：

1.4 我只希望我的Swagger在生产环境中使用，在发布的时候不使用。怎么实现？

• 1. 判断是不是生产环境，是则 flag = false，否则 flag = true
• 2. 注入enable（flag）

---

1.4.1 准备工作，新建2个配置文件

application.properties

spring.profiles.active=dev

application-dev.properties

server.port=8081

application-pro.properties

server.port=8082

---

1.4.2 代码实现

SwaggerConfig.java

    /**
     * 配置docket以配置Swagger具体参数
     */
    @Bean
    // org.springframework.core.env.Environment
    public Docket docket(Environment environment) {
        // 设置要显示swagger的环境 这里是 dev 和 test 环境
        // org.springframework.core.env.Profiles
        Profiles profiles = Profiles.of("dev", "test");
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean flag = environment.acceptsProfiles(profiles);


        // enable(boolean) 表示是否启用Swagger 默认为true(启用) 如果为false,则Swagger不能在游览器中访问
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(flag).select().apis(RequestHandlerSelectors.basePackage("com.tian.swagger.controller")).paths(PathSelectors.ant("/tian/**")).build();
    }

启动测试01：Profiles 里面包含 dev

启动测试01：Profiles 里面不包含 dev

Profiles profiles = Profiles.of("test");

---

---