SpringBoot整合Swigger2_spring swigger-优快云博客

本文链接：https://blog.youkuaiyun.com/zhiwenganyong/article/details/122584887

本文详细介绍了如何在SpringBoot项目中集成Swagger，包括环境搭建、配置步骤及使用技巧。通过配置Docket实例来定制Swagger参数，并展示了如何扫描接口、配置文档信息及分组等。

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

Swigger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：

                1. 接口的文档在线自动生成
                2. 功能测试
                3.支持多种语言（如：Java，PHP等）

官网： API Documentation & Design Tools for Teams | Swaggerhttps://swagger.io/

Swagger 和 Springfox-Swagger 的关系

Swagger 是一种规范。

springfox-swagger 是基于 Spring 生态系统的该规范的实现。

springfox-swagger-ui 是对 swagger-ui 的封装，使得其可以使用 Spring 的服务。

Springfox Reference Documentationhttps://springfox.github.io/springfox/docs/snapshot/#answers-to-common-questions-and-problems

SpringBoot集成Swagger

要求

jdk 1.8 + 否则swagger2无法运行

Maven依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger2</artifactId>
   <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>

编写SwaggerConfig文件，统一配置 Swagger

添加注解

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置

导入的是这两个注解

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

启动SpringBoot-web项目，然后打开如下网址可以看到Swagger的UI界面

http://localhost:8080/swagger-ui.html

如果引用的是springfox-swagger-ui3.0

访问地址为

http://localhost:8080/swagger-ui/index.html

配置Swagger

1、Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2);
    }

2、可以通过apiInfo()属性配置文档信息

    //配置文档信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("联系人名字", "", "联系人访问链接");
        return new ApiInfo(
                "Swagger API文档",
                "Swagger自动生成接口的文档",
                "版本",
                "组织链接",
                contact,
                "Apach 2.0 许可",
                "许可链接",
                new ArrayList()
        );
    }

3、Docket 实例关联上 apiInfo()

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

4、重启项目，访问测试,看下效果

http://localhost:8080/swagger-ui.html

配置扫描接口

1、构建Docket时通过select()方法配置怎么扫描接口。

@Bean
public Docket docket() {
   return new Docket(DocumentationType.SWAGGER_2)
      .apiInfo(apiInfo())
      .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
      .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
      .build();
}

新建controller，如TestController

文件结构如下

@Api(tags = "测试")，这个加在类上，然后会被Swagger扫描到，tag指定了该Controller的名字。@ApiOperation(value = "测试方法")加在方法上，value定义了名字。

@Controller
@Api(tags = "测试")
public class TestController {

    @RequestMapping("/test")
    @ApiOperation(value = "测试方法")
    public void test() {

    }

}

2、重启项目测试

可以看到TestController

可以看到定义的方法，以及不同的请求

打开Get请求，可以进行在线测试。

还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

any() // 扫描所有，项目中的所有接口都会被扫描到
none() // 不扫描接口
// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
withMethodAnnotation(final Class<? extends Annotation> annotation)
// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
withClassAnnotation(final Class<? extends Annotation> annotation)
basePackage(final String basePackage) // 根据包路径扫描接口

配置Swagger开关

1、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .build();
    }

注：当项目上线时记得关闭Swagger,不然耗内存同时也不安全

配置API分组

配置了分组可以在如下位置看到，没设置API默认在default

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .groupName("test") // 配置分组
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .build();
    }

重启项目，可以看到test组

如何配置多个分组？

配置多个分组只需要配置多个docket即可，下面配置了三个docket，组名分别为test1,test2,test3

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket1() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .groupName("test1") // 配置分组
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .build();
    }

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket2() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .groupName("test2") // 配置分组
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .build();
    }

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket3() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .enable(true) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .groupName("test3") // 配置分组
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .build();
    }

重启项目，可以看到配置的组

实体配置

1、新建一个实体类Test.java

这里我就简单的，只有两个属性

public class Test {

    /**
     * 主键
     */
    private String ID;

    /**
     * 姓名
     */
    private String Name;


}

这里用到两个主键：

@ApiModel("")、@ApiModelProperty("")

给Test加上注解

@ApiModel("测试实体类")
public class Test {

    /**
     * 主键
     */
    @ApiModelProperty("主键")
    private String ID;

    /**
     * 姓名
     */
    @ApiModelProperty("姓名")
    private String Name;


}

2.如何在UI界面上显示实体类

只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中

    @RequestMapping("/test")
    @ApiOperation(value = "测试方法")
    public Test test() {
        return new Test();
    }

3.重启项目，看看效果

可以看到测试实体类