java

关注公众号 jb51net

关闭
首页 > 软件编程 > java > SpringBoot Swagger2可视化API文档

SpringBoot集成Swagger2构建可视化API文档的完整步骤

作者:越来越无动于衷

在前后端分离开发中,API文档是连接前后端的重要桥梁,Swagger作为一款强大的API文档工具,能自动生成交互式API文档,极大提升开发效率,本文将详细介绍SpringBoot项目集成Swagger2的完整步骤,包含配置细节、常见问题及解决方案,需要的朋友可以参考下

一、Swagger 简介

Swagger 是一套用于生成、描述和调用 RESTful API 的规范和工具,主要优势包括:

二、环境准备

基础环境

三、集成步骤

1. 添加 Swagger2 依赖

在 pom.xml 中添加 Swagger2 核心依赖(springfox-swagger2 和 springfox-swagger-ui):

<!-- Swagger2 核心依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- Swagger2 可视化界面 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

注意:Spring Boot 2.6+ 及 3.x 版本与 Swagger2(2.9.2)存在一定兼容性问题,需通过后续配置解决(见步骤 3)。

 如果不成功可以

2. 配置 Swagger 核心类

创建 SwaggerConfig 配置类,用于自定义 Swagger 文档信息、扫描规则等:

package com.qcby.springboot.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@Configuration // 标识为配置类
@EnableSwagger2 // 启用 Swagger2
public class SwaggerConfig implements WebMvcConfigurer {
 
    /**
     * 配置 Swagger 核心对象 Docket
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2) // 指定 Swagger 版本为 2.x
                .apiInfo(apiInfo()) // 配置 API 文档基本信息
                .select()
                // 配置接口扫描规则:只扫描带有 @ApiOperation 注解的方法
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any()) // 匹配所有路径
                .build()
                .enable(true); // 是否启用 Swagger(生产环境可设为 false 关闭)
    }
 
    /**
     * 配置 API 文档页面信息(标题、描述、版本等)
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot API 文档") // 文档标题
                .description("接口文档详情:包含用户管理、数据查询等接口") // 文档描述
                .version("1.0.0") // 接口版本
                .contact(new Contact("开发者", "https://xxx.com", "xxx@example.com")) // 联系人信息
                .license("Apache 2.0") // 许可协议
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0") // 许可协议链接
                .build();
    }
 
    /**
     * 配置静态资源映射(解决 Swagger UI 页面无法访问问题)
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射 Swagger UI 静态资源
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 映射 webjars 静态资源(Swagger UI 依赖的前端资源)
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        // 映射项目自定义静态资源(如需要)
        registry.addResourceHandler("/**")
                .addResourceLocations("classpath:/static/");
    }
}

3. 解决 Spring Boot 版本兼容问题

Spring Boot 2.6+ 及 3.x 版本默认使用 PathPatternParser 作为路径匹配策略,与 Swagger2 存在冲突,需手动切换为 AntPathMatcher

在 application.yml 中添加配置:

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher # 切换为 Ant 风格路径匹配器

4. 编写 API 接口并添加 Swagger 注解

在 Controller 中使用 Swagger 注解描述接口,生成更详细的文档:

package com.qcby.springboot.controller;
 
import com.qcby.springboot.entity.Person;
import com.qcby.springboot.service.PersonService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
 
import java.util.List;
 
@Api(tags = "人员管理接口") // 描述类的作用
@Controller
@RequestMapping("/person")
public class PersonController {
 
    @Autowired
    private PersonService personService;
 
    @ApiOperation(value = "查询所有人员", notes = "获取数据库中所有人员信息列表") // 描述方法作用
    @RequestMapping("/findAll")
    @ResponseBody
    public List<Person> findAll() {
        return personService.findAll();
    }
 
    @ApiOperation(value = "添加人员", notes = "根据传入的人员信息新增一条记录")
    @RequestMapping("/insert")
    @ResponseBody
    public String insert(
            @ApiParam(name = "person", value = "人员实体对象", required = true) // 描述参数
            Person person) {
        int result = personService.insert(person);
        return result > 0 ? "插入成功" : "插入失败";
    }
 
    @ApiOperation(value = "删除人员", notes = "根据 ID 删除指定人员记录")
    @RequestMapping("/delete")
    @ResponseBody
    public String delete(
            @ApiParam(name = "id", value = "人员 ID", required = true, example = "1")
            Integer id) {
        int result = personService.delete(id);
        return result > 0 ? "删除成功" : "删除失败";
    }
}

常用 Swagger 注解说明:

5. 访问 Swagger UI 文档

启动 Spring Boot 项目,访问以下地址:
http://localhost:8080/swagger-ui.html

成功访问后,将看到如下界面:

可直接在页面上输入参数,点击「Try it out」测试接口,无需额外工具。

四、常见问题及解决方案

1. 访问 swagger-ui.html 出现 404 错误

2. 接口未在 Swagger 文档中显示

3. Spring Boot 3.x 兼容问题

Swagger2(springfox)对 Spring Boot 3.x 支持有限,推荐使用 OpenAPI 3.0 替代方案(springdoc-openapi):

<!-- 替代 Swagger2 的 OpenAPI 3.0 依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

以上就是SpringBoot集合Swagger2构建可视化API文档的完整步骤的详细内容,更多关于SpringBoot Swagger2可视化API文档的资料请关注脚本之家其它相关文章!

您可能感兴趣的文章:
阅读全文