SpringBoot集成Swagger_new docket(-优快云博客

本文介绍了如何在SpringBoot项目中集成Swagger，包括配置Swagger、扫描接口、控制开关、设置API分组、处理实体类以及使用各种注解。此外，还提到了不同主题的Swagger主页和参考代码。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

文章目录

SpringBoot集成Swagger

1、建立一个SpringBoot项目
2、导入依赖

 <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>

3、编写swagger配置类

@Configuration
@EnableSwagger2//开启Swagger2的自动配置
public class SwaggerConfig {
}

4、打开网页http://localhost:8080/swagger-ui.html，可以看见swagger网页则成功。

配置Swagger

1、通过配置Swagger的实例Docket来配置Swagger

  //Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger。
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

2、配置文档信息

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

        Contact contact = new Contact("xhj", "www.xxx.com", "xxxxx.qq.com");
        return new ApiInfo( "title","description","version","termsOfServiceUrl",contact,"license","licenseUrl",new ArrayList());

    }

由于源码中只有一个构造方法，没有set方法，所以只能通过构造方法配置信息。

Swagger配置扫描接口

1、通过select方法扫描接口

 @Bean
    public Docket docket() {
        //any扫描项目中的所有接口
        //none不扫描接口
        //withMethodAnnotation(final Class<? extends Annotation> annotation),通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有 controller注解的类中的接口
        //basePackage(final String basePackage),根据包路径扫描接口
        //regex(final String pathRegex),通过正则表达式控制
        //ant(final String antPattern),通过ant()控制
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors 配置如何扫描接口
                .select()
                //basePackage指定要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.xhj.controller"))
                .paths(PathSelectors.ant("/xhj/**"))//配置如何通过path过滤,即这里只扫描请求以/xhj开头的接口
                .build()
                ;
    }

any：扫描项目中的所有接口
none：不扫描接口
withMethodAnnotation(final Class<? extends Annotation> annotation)：通过类上的注解扫描如.withClassAnnotation(Controller.class)只扫描有 controller注解的类中的接口
basePackage(final String basePackage)：根据包路径扫描接口
regex(final String pathRegex)：通过正则表达式控制
ant(final String antPattern)：通过ant()控制

配置Swagger开关

1、在Docket类中配置enable()方法，如果是false则浏览器不能访问
2、动态配置不同环境中的enable()

首先需要获取当前环境信息

   @Bean
    public Docket docket(Environment environment) {

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

根据获取到的环境信息使用environment.acceptsProfiles()方法判断
将方法放回的值注入到enable()中

.enable(b)

配置API分组

默认分组是default
在这里插入图片描述

可以通过groupName()方法定义分组

 .groupName("hello") // 配置分组

在这里插入图片描述

如果需要设置多个分组，只能配置多个docket

 @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("第二组");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("第三组");
    }
    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("第四组");
    }

在这里插入图片描述每一个分组都对应着一个Docket，在实际开发中，每个开发人员负责管理自己的Docket。实现协同开发。

配置实体类

1、只要在扫描包内的接口都会被扫描到，所以只需要将实体类做成接口，放在Controller中

   @RequestMapping("/user")
    public User User(){
        return new User();
    }

2、可以通过注解添加注释

@Repository
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("姓名")
    public String name;
    @ApiModelProperty("密码")
    public String password;
}

效果图：
在这里插入图片描述

常用注解

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

主页换肤

导入不同的依赖，会有不同的主页

默认的访问 http://localhost:8080/swagger-ui.html

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

bootstrap-ui 访问 http://localhost:8080/doc.html

    <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.1</version>
        </dependency>

Layui-ui 访问 http://localhost:8080/docs.html

  <dependency>
            <groupId>com.github.caspar-chen</groupId>
            <artifactId>swagger-ui-layer</artifactId>
            <version>1.1.3</version>
        </dependency>

mg-ui 访问 http://localhost:8080/document.html

<dependency>
            <groupId>com.zyplayer</groupId>
            <artifactId>swagger-mg-ui</artifactId>
            <version>1.0.6</version>
        </dependency>

Swagger配置类参考代码：

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
@EnableSwagger2//开启Swagger2的自动配置
public class SwaggerConfig {

    //Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swagger。
    @Bean
    public Docket docket(Environment environment) {

        // 设置要显示swagger的环境
        Profiles of = Profiles.of("dev", "test");
        // 判断当前是否处于该环境
        // 通过 enable() 接收此参数判断是否要显示
        boolean b = environment.acceptsProfiles(of);
        //any扫描项目中的所有接口
        //none不扫描接口
        //withMethodAnnotation(final Class<? extends Annotation> annotation),通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有 controller注解的类中的接口
        //basePackage(final String basePackage),根据包路径扫描接口
        //regex(final String pathRegex),通过正则表达式控制
        //ant(final String antPattern),通过ant()控制
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("hello") // 配置分组
                .enable(b)
                // 通过.select()方法，去配置扫描接口,RequestHandlerSelectors 配置如何扫描接口
                .select()
                //basePackage指定要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.xhj.controller"))
                .paths(PathSelectors.ant("/xhj/**"))//配置如何通过path过滤,即这里只扫描请求以/xhj开头的接口
                .build()
                ;
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("第二组");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("第三组");
    }
    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("第四组");
    }

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

        Contact contact = new Contact("xhj", "www.xxx.com", "xxxxx.qq.com");
        return new ApiInfo( "title","description","version","termsOfServiceUrl",contact,"license","licenseUrl",new ArrayList());

    }

}