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文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

相关文章

  • SpringBoot三种打包方法举例详解

    SpringBoot三种打包方法举例详解

    这篇文章主要给大家介绍了关于SpringBoot三种打包方法的相关资料,Spring Boot是一个开发框架,目的是简化Spring应用的初始搭建过程和开发过程,文中提供了3种打包方法,需要的朋友可以参考下
    2023-12-12
  • Java面试最容易被刷的重难点之锁的使用策略

    Java面试最容易被刷的重难点之锁的使用策略

    锁像synchronized同步块一样,是一种线程同步机制,但比Java中的synchronized同步块更复杂。因为锁(以及其它更高级的线程同步机制)是由synchronized同步块的方式实现的,所以我们还不能完全摆脱synchronized关键字
    2021-10-10
  • 详解如何在SpringBoot里使用SwaggerUI

    详解如何在SpringBoot里使用SwaggerUI

    本篇文章主要介绍了详解如何在SpringBoot里使用SwaggerUI,小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧
    2018-02-02
  • SpringBoot在IDEA中实现热部署的步骤

    SpringBoot在IDEA中实现热部署的步骤

    这篇文章主要介绍了SpringBoot在IDEA中实现热部署的步骤,帮助大家更好的理解和使用springboot框架,感兴趣的朋友可以了解下
    2020-11-11
  • Java制作验证码的完整实例代码

    Java制作验证码的完整实例代码

    这篇文章主要给大家介绍了关于Java制作验证码的完整实例代码,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧
    2020-11-11
  • MyBatis中#{}和${}的区别详解

    MyBatis中#{}和${}的区别详解

    mybatis和ibatis总体来讲都差不多的。下面小编给大家探讨下mybatis中#{}和${}的区别,感兴趣的朋友一起学习吧
    2016-08-08
  • Spring Boot中KafkaListener的介绍、原理和使用方法案例详解

    Spring Boot中KafkaListener的介绍、原理和使用方法案例详解

    本文介绍了Spring Boot中 @KafkaListener 注解的介绍、原理和使用方法,通过本文的介绍,我们希望读者能够更好地理解Spring Boot中 @KafkaListener 注解的使用方法,并在项目中更加灵活地应用
    2023-09-09
  • ResultSet如何动态获取列名和值

    ResultSet如何动态获取列名和值

    这篇文章主要介绍了ResultSet如何动态获取列名和值问题,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2022-12-12
  • Java由浅入深细数数组的操作上

    Java由浅入深细数数组的操作上

    数组对于每一门编程语言来说都是重要的数据结构之一,当然不同语言对数组的实现及处理也不尽相同。Java 语言中提供的数组是用来存储固定大小的同类型元素
    2022-04-04
  • SpringBoot中使用@Async实现异步调用​方法示例

    SpringBoot中使用@Async实现异步调用​方法示例

    在Spring Boot中异步调用是通过Spring的@Async注解来实现的,它允许我们在不阻塞主线程的情况下执行耗时的操作,这篇文章主要介绍了SpringBoot中使用@Async实现异步调用​方法的相关资料,需要的朋友可以参考下
    2025-12-12

最新评论