快捷導(dǎo)航

SpringBoot3集成swagger文檔的使用方法

更新時(shí)間：2025年01月07日 09:49:42 作者：java_學(xué)習(xí)愛(ài)好者

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

一、前言

為了方便后端人員進(jìn)行進(jìn)行接口測(cè)試，swagger就此誕生

1. API 文檔自動(dòng)生成

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

2. 交互式 API 測(cè)試

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

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

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

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

二、使用方法

1.導(dǎo)入依賴(lài)

        <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()
                // 接口文檔標(biāo)題
                .info(new Info().title("在線(xiàn)考試系統(tǒng)API接口文檔")
                        // 接口文檔簡(jiǎn)介
                        .description("這是基于Knife4j OpenApi3的在線(xiàn)考試系統(tǒng)接口文檔")
                        // 接口文檔版本
                        .version("v1.0")
                        // 開(kāi)發(fā)者聯(lián)系方式
                        .contact(new Contact().name("黃宏保").email("3111871135@qq.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("在線(xiàn)考試系統(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("學(xué)生管理模塊")
                .pathsToMatch("/user/**", "/student/**")
                .build();
    }
}

application.yaml配置

springdoc:
  swagger-ui:
    path: /swagger-ui.html # 自定義Swagger前端請(qǐng)求路徑
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs # Swagger后端請(qǐng)求地址
    enabled: true # 是否開(kāi)啟文檔功能
# knife4j相關(guān)配置
knife4j:
  enable: true # 開(kāi)啟knife4j，無(wú)需添加@EnableKnife4j注解
  setting:
    language: zh_cn # 中文

3.常見(jiàn)注解

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