快捷導航

SpringBoot3集成swagger文檔的使用方法

更新時間：2025年01月07日 09:49:42 作者：java_學習愛好者

本文介紹了Swagger的誕生背景、主要功能以及如何在Spring Boot 3中集成Swagger文檔,Swagger可以幫助自動生成API文檔,實現(xiàn)與代碼同步,并提供交互式測試功能,使用方法包括導入依賴、配置文檔、使用常見注解以及訪問生成的Swagger UI和文檔,感興趣的朋友跟隨小編一起看看吧

一、前言

為了方便后端人員進行進行接口測試，swagger就此誕生

1. API 文檔自動生成

減少文檔編寫工作：通過在代碼中使用注解，Swagger 可以自動生成詳細的 API 文檔，減少了手動編寫文檔的工作量。
保持文檔與代碼同步：由于文檔是直接從代碼生成的，因此可以確保文檔總是與實際的 API 實現(xiàn)保持一致。

2. 交互式 API 測試

實時測試 API：Swagger UI 提供了一個基于瀏覽器的界面，允許開發(fā)者直接從瀏覽器調(diào)用 API 并查看響應結(jié)果，這有助于快速測試 API 功能。

參數(shù)輸入與驗證：用戶可以直接在界面上輸入?yún)?shù)并發(fā)送請求，Swagger 會自動處理參數(shù)格式和驗證。

3. API 設(shè)計和開發(fā)協(xié)作

統(tǒng)一的 API 規(guī)范：Swagger 使用 OpenAPI 規(guī)范（以前稱為 Swagger 規(guī)范），這是一種標準的 API 描述格式，使得團隊成員可以更容易理解和遵循 API 設(shè)計。
前后端分離開發(fā)：前端和后端開發(fā)者可以通過 Swagger 文檔進行溝通，即使在后端 API 還未完成時，前端也可以開始基于文檔進行開發(fā)。

二、使用方法

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("在線考試系統(tǒng)API接口文檔")
                        // 接口文檔簡介
                        .description("這是基于Knife4j OpenApi3的在線考試系統(tǒng)接口文檔")
                        // 接口文檔版本
                        .version("v1.0")
                        // 開發(fā)者聯(lián)系方式
                        .contact(new Contact().name("黃宏保").email("3111871135@qq.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("在線考試系統(tǒng)接口文檔")//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相關(guān)配置
knife4j:
  enable: true # 開啟knife4j，無需添加@EnableKnife4j注解
  setting:
    language: zh_cn # 中文

3.常見注解

@Tag(name = "用戶管理")//用于在控制器類上標注，指示該控制器的相關(guān)信息
@Operation(summary = "登錄")//用于在控制器方法上標注，指示該方法的作用、描述等
@Schema(description = "用戶信息")//在DTO類上標注，用于描述一個實體類
@Schema(description = "用戶信息")//用于描述實體類的屬性(自己定義的接收變量)，即類的字段
@Parameter(description = "郵箱") //定義在控制層方法的參數(shù)上