SpringBoot3集成swagger文档的使用方法

 更新时间:2025年01月07日 09:49:42   作者:java_学习爱好者  
本文介绍了Swagger的诞生背景、主要功能以及如何在Spring Boot 3中集成Swagger文档,Swagger可以帮助自动生成API文档,实现与代码同步,并提供交互式测试功能,使用方法包括导入依赖、配置文档、使用常见注解以及访问生成的Swagger UI和文档,感兴趣的朋友跟随小编一起看看吧

一、前言

为了方便后端人员进行进行接口测试,swagger就此诞生

1. API 文档自动生成

  • 减少文档编写工作:通过在代码中使用注解,Swagger 可以自动生成详细的 API 文档,减少了手动编写文档的工作量。
  • 保持文档与代码同步:由于文档是直接从代码生成的,因此可以确保文档总是与实际的 API 实现保持一致。

2. 交互式 API 测试

实时测试 API:Swagger UI 提供了一个基于浏览器的界面,允许开发者直接从浏览器调用 API 并查看响应结果,这有助于快速测试 API 功能。

参数输入与验证:用户可以直接在界面上输入参数并发送请求,Swagger 会自动处理参数格式和验证。

3. API 设计和开发协作

  • 统一的 API 规范:Swagger 使用 OpenAPI 规范(以前称为 Swagger 规范),这是一种标准的 API 描述格式,使得团队成员可以更容易理解和遵循 API 设计。
  • 前后端分离开发:前端和后端开发者可以通过 Swagger 文档进行沟通,即使在后端 API 还未完成时,前端也可以开始基于文档进行开发。

二、使用方法

1.导入依赖

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
            <version>4.3.0</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.15.2</version> 
        </dependency>

2.文档配置

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                // 接口文档标题
                .info(new Info().title("在线考试系统API接口文档")
                        // 接口文档简介
                        .description("这是基于Knife4j OpenApi3的在线考试系统接口文档")
                        // 接口文档版本
                        .version("v1.0")
                        // 开发者联系方式
                        .contact(new Contact().name("黄宏保").email("3111871135@qq.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("在线考试系统接口文档")//swagger-ui文档地址
                        .url("http://127.0.0.1:8088"));
    }
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder().group("管理员管理模块")
                .pathsToMatch("/user/**","/admin/**")
                .build();
    }
    @Bean
    public GroupedOpenApi teacherApi() {
        return GroupedOpenApi.builder().group("教师管理模块")
                .pathsToMatch("/user/**", "/teacher/**")
                .build();
    }
    @Bean
    public GroupedOpenApi studentApi() {
        return GroupedOpenApi.builder().group("学生管理模块")
                .pathsToMatch("/user/**", "/student/**")
                .build();
    }
}

 application.yaml配置

springdoc:
  swagger-ui:
    path: /swagger-ui.html # 自定义Swagger前端请求路径
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs # Swagger后端请求地址
    enabled: true # 是否开启文档功能
# knife4j相关配置
knife4j:
  enable: true # 开启knife4j,无需添加@EnableKnife4j注解
  setting:
    language: zh_cn # 中文

3.常见注解

@Tag(name = "用户管理")//用于在控制器类上标注,指示该控制器的相关信息
@Operation(summary = "登录")//用于在控制器方法上标注,指示该方法的作用、描述等
@Schema(description = "用户信息")//在DTO类上标注,用于描述一个实体类
@Schema(description = "用户信息")//用于描述实体类的属性(自己定义的接收变量),即类的字段
@Parameter(description = "邮箱") //定义在控制层方法的参数上

4.效果展示

5.访问路径

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

swagger文档路径:http://127.0.0.1:8080/doc.html#/home

到此这篇关于SpringBoot3集成swagger文档的文章就介绍到这了,更多相关SpringBoot3集成swagger文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

相关文章

  • 举例讲解Java设计模式编程中Decorator装饰者模式的运用

    举例讲解Java设计模式编程中Decorator装饰者模式的运用

    这篇文章主要介绍了Java设计模式编程中Decorator装饰者模式的运用,装饰者模式就是给一个对象动态的添加新的功能,装饰者和被装饰者实现同一个接口,装饰者持有被装饰者的实例,需要的朋友可以参考下
    2016-05-05
  • 为什么Spring和IDEA都不推荐使用 @Autowired 注解

    为什么Spring和IDEA都不推荐使用 @Autowired 注解

    本文主要介绍了为什么Spring和IDEA都不推荐使用 @Autowired 注解,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2022-04-04
  • SpringBoot注解@Import原理之关于ConfigurationClassPostProcessor源码解析

    SpringBoot注解@Import原理之关于ConfigurationClassPostProcessor源码解析

    这篇文章主要介绍了SpringBoot注解@Import原理之关于ConfigurationClassPostProcessor源码解析,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
    2024-07-07
  • org.apache.ibatis.binding.BindingException异常报错原因以及详细解决方案

    org.apache.ibatis.binding.BindingException异常报错原因以及详细解决方案

    这篇文章主要给大家介绍了关于org.apache.ibatis.binding.BindingException异常报错原因以及详细解决方案的相关资料,文中通过实例代码介绍的非常详细,需要的朋友可以参考下
    2023-02-02
  • MyBatis配置不同级别的日志输出

    MyBatis配置不同级别的日志输出

    MyBatis提供多种日志框架集成,如SLF4J、Log4j2、Logback等,通过配置日志框架和调整日志级别,可以实现详细的SQL日志记录,本文就来介绍一下,感兴趣的可以了解一下
    2024-12-12
  • Java深入分析与解决Top-K问题

    Java深入分析与解决Top-K问题

    TopK问题即在N个数中找出最大的前K个,这篇文章将详细讲解三种方法解决TopK问题,文中代码具有一定参考价值,快跟随小编一起学习一下吧
    2022-04-04
  • SpringBoot配置系统全局异常映射处理

    SpringBoot配置系统全局异常映射处理

    在项目开发中,肯定少不了异常的出现,作为后台开发人员,我们总是在不停的写各种接口提供给前端调用,然而不可避免的,当后台出现BUG时,前端总是丑陋的讲错误信息直接暴露给用户,这样的用户体验想必是相当差的,本文主要讲解异常映射的配置
    2021-06-06
  • 解决Maven中的依赖导包问题(组合技巧)

    解决Maven中的依赖导包问题(组合技巧)

    自从我开始接触了以spring为框架的项目学习后,这个maven导包老是出现问题,每次在这个上面花费好多时间,于是乎打算写一个秘籍出来,这篇文章主要介绍了解决Maven中的依赖导包问题,需要的朋友可以参考下
    2023-11-11
  • Java之synchronized(含与ReentrantLock的区别解读)

    Java之synchronized(含与ReentrantLock的区别解读)

    文章主要介绍了`synchronized`和`ReentrantLock`的区别,包括它们的实现原理、公平性、灵活性、可中断性等方面,同时,文章详细解释了`synchronized`的使用方法,包括修饰实例方法、静态方法和代码块的情况,以及如何分析代码是否互斥和可重入性
    2025-01-01
  • Java字符流和字节流对文件操作的区别

    Java字符流和字节流对文件操作的区别

    本篇文章主要介绍了Java的IO流分为字符流(Reader,Writer)和字节流(InputStream,OutputStream),字节流顾名思义字节流就是将文件的内容读取到字节数组,对初学者很有用,有需要的朋友可以了解一下。
    2016-10-10

最新评论