SpringDoc和Swagger使用示例詳解

更新時(shí)間：2025年11月27日 10:12:54 作者：q***1884

Swagger和Springdoc是兩個(gè)常用的工具,用于生成和維護(hù)API文檔,特別是針對(duì)基于REST的Web服務(wù),這篇文章給大家介紹SpringDoc和Swagger使用示例,感興趣的朋友跟隨小編一起看看吧

Swagger和Springdoc是兩個(gè)常用的工具，用于生成和維護(hù)API文檔，特別是針對(duì)基于REST的Web服務(wù)。它們有效地提升了API的可讀性和可維護(hù)性，幫助開發(fā)者、產(chǎn)品經(jīng)理和其他利益相關(guān)者更好地理解和使用所提供的API。

注意：Swagger支持springboot2.0但不支持springboot3.0

一、SpringDoc

Springdoc是一個(gè)開源的庫，旨在將Spring Boot項(xiàng)目的RESTful API與OpenAPI 3文檔生成器集成。Springdoc與Spring Boot應(yīng)用無縫集成，并支持包括Swagger UI在內(nèi)的多種用戶界面。

1.添加依賴

    <dependencies>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.6.0</version>
        </dependency>
    </dependencies>

2.配置代碼

添加一個(gè)配置類，并添加xml配置

配置解釋

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha

（1）springdoc.api-docs.path

屬性路徑:springdoc.api-docs.path

作用: 定義 OpenAPI 文檔的訪問路徑。

默認(rèn)值:/v3/api-docs

示例:

springdoc:
  api-docs:
    path: /v3/api-docs

配置后，API 文檔可以通過http://<host>:<port>/v3/api-docs訪問。

（2）springdoc.swagger-ui.path

屬性路徑:springdoc.swagger-ui.path
作用: 定義 Swagger UI 的訪問路徑。
默認(rèn)值:/swagger-ui.html
示例:

springdoc:
  swagger-ui:
    path: /swagger-ui.html

配置后，Swagger UI 可以通過http://<host>:<port>/swagger-ui.html訪問。

（3）springdoc.swagger-ui.operationsSorter

屬性路徑:springdoc.swagger-ui.operationsSorter
作用: 定義如何對(duì) Swagger UI 中的操作進(jìn)行排序。
可選值:
- alpha: 按照操作名稱的字母順序排列。
- method: 按照 HTTP 方法進(jìn)行排序（如 GET, POST, PUT, DELETE）。
示例:

springdoc:
  swagger-ui:
    operationsSorter: method

配置后，操作會(huì)按照 HTTP 方法的順序顯示。

（4）springdoc.swagger-ui.tagsSorter

屬性路徑:springdoc.swagger-ui.tagsSorter
作用: 定義如何對(duì) Swagger UI 中的標(biāo)簽進(jìn)行排序。
可選值:
- alpha: 按照標(biāo)簽名稱的字母順序排列。
示例:

springdoc:
  swagger-ui:
    tagsSorter: alpha

配置后，標(biāo)簽會(huì)按照字母順序顯示。

（5）springdoc.title

屬性路徑:springdoc.title
作用: 設(shè)置整個(gè) API 文檔的標(biāo)題。
示例:

springdoc:
  title: 用戶管理

配置后，生成的 API 文檔的標(biāo)題會(huì)顯示為“用戶管理”。

使用

package com.ck.framework.common.springdoc.config;
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.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
 * @ClassName SpringDocConfig
 * @Description
 * @Author 
 * @Date 2024/8/28 15:55
 * @Version 1.0
 */
@Configuration
public class SpringDocConfig {
    @Autowired
    private BaseConfig baseConfig;
    @Bean
    public OpenAPI createOpenApi() {
        return new OpenAPI()
                .info(createInfo());
    }
    private Info createInfo() {
        return new Info()
                .contact(createContact())
                .title(baseConfig.getTitle())
                .description(baseConfig.getDescription())
                .version(baseConfig.getVersion());
    }
    private Contact createContact() {
        Contact contact = new Contact();
        contact.name(baseConfig.getContactName());
        contact.url(baseConfig.getContactUrl());
        contact.email(baseConfig.getContactEmail());
        return contact;
    }
}

3.控制器處理

需要再Controller里面加上Tag注解

package com.ck.framework.user.controller;
import com.ck.framework.common.web.bean.Result;
import com.ck.framework.user.entity.PageResult;
import com.ck.framework.user.entity.dto.UserDto;
import com.ck.framework.user.entity.po.UserPo;
import com.ck.framework.user.entity.req.UserListReq;
import com.ck.framework.user.entity.req.UserReq;
import com.ck.framework.user.service.UserService;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
/**
 * @ClassName UserController
 * @Description
 * @Author 
 * @Date 2024/8/24 0:03
 * @Version 1.0
 */
@RestController
@RequestMapping("/user")
@Tag(name = "用戶管理")
public class UserController {
    @Autowired
    private UserService userService;
    @PostMapping
    public Result<Boolean> addUser(@RequestBody UserReq userReq) {
        UserDto userDto = new UserDto();
        userDto.setName(userReq.getName());
        userDto.setAge(userReq.getAge());
        int num = userService.addUser(userDto);
        if (num > 0) {
            return Result.success(true);
        } else {
            return Result.fail();
        }
    }
    @DeleteMapping("/{id}")
    public Result<Boolean> deleteUser(@RequestBody UserReq userReq) {
        UserDto userDto = new UserDto();
        userDto.setId(userReq.getId());
        int num = userService.delUser(userDto);
        if (num > 0) {
            return Result.success(true);
        } else {
            return Result.fail();
        }
    }
    @GetMapping
    public Result<PageResult<UserPo>> getUserPage(@RequestBody UserListReq userListReq) {
        UserDto userDto = new UserDto();
        userDto.setPageIndex(userListReq.getPageIndex());
        userDto.setPageSize(userListReq.getPageSize());
        PageResult<UserPo> pageResult = userService.getUserPage(userDto);
        return Result.success(pageResult);
    }
}

4.訪問

5.優(yōu)點(diǎn)

無縫集成:
- 專為 Spring Boot 設(shè)計(jì)，非常容易集成到 Spring Boot 應(yīng)用中。
減少注解:
- 可以自動(dòng)解析 Spring MVC 或 Spring WebFlux 控制器，減少了需要添加的注解數(shù)量。
自動(dòng)化配置:
- 大量依賴默認(rèn)配置，無需復(fù)雜的手動(dòng)配置，開箱即用。
支持最新技術(shù):
- 支持 Spring Boot 2.x 及更高版本，跟進(jìn) Spring 生態(tài)系統(tǒng)的最新發(fā)展。
豐富的文檔和示例:
- 提供了良好的文檔和示例，幫助開發(fā)者快速上手。

6.缺點(diǎn)

局限性:
- 專門面向 Spring Boot 項(xiàng)目，不適用于其他框架或原生 Spring 項(xiàng)目。
功能相對(duì)簡單:
- 相對(duì)于 Swagger 提供的完整工具鏈，Springdoc 的功能相對(duì)單一，主要聚焦于文檔生成。

二、swagger

Swagger是一個(gè)用于生成、描述、調(diào)用和可視化 RESTful Web 服務(wù)的開源框架。它的核心是一個(gè)名為 OpenAPI 規(guī)范的描述性語言。Swagger 是 Java 應(yīng)用程序中常用的工具之一，因?yàn)樗茏詣?dòng)生成 API 文檔，并提供一個(gè)用戶友好的接口來測(cè)試 API。

在 Java 項(xiàng)目中使用 Swagger 通常包括以下步驟：

1. 添加依賴項(xiàng)

首先，你需要在你的項(xiàng)目中添加所需的 Swagger 依賴項(xiàng)。以 Maven 項(xiàng)目為例，在pom.xml文件中添加以下依賴：

    <dependencies>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>
    </dependencies>

2. 配置 Swagger

添加一個(gè) Swagger 配置類。例如，在 Spring Boot 應(yīng)用程序中，你可以添加以下內(nèi)容：

package com.ck.framework.common.swagger.config;
import org.springframework.context.annotation.Configuration;
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;
/**
 * @ClassName SwaggerConfig
 * @Description 配置Swagger的類，啟用Swagger并定義API文檔的相關(guān)信息
 * @Author 
 * @Date 2024/8/28 08:31
 * @Version 1.0
 */
@Configuration  // 表示這是一個(gè)配置類
@EnableSwagger2  // 啟用Swagger2
public class SwaggerConfig {
    /**
     * 創(chuàng)建一個(gè)Docket Bean，用于配置Swagger的核心內(nèi)容，包括哪些包中的API需要生成文檔和API的基本信息。
     *
     * @return Docket對(duì)象，用于Swagger的配置
     */
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // 指定文檔類型為Swagger2
                .apiInfo(apiInfo())  // 配置API信息
                .select()  // 返回一個(gè)ApiSelectorBuilder實(shí)例，用于控制哪些接口暴露給swagger
                .apis(RequestHandlerSelectors.basePackage("com.ck.framework.common.swagger"))  // 選擇掃描的包名
                .paths(PathSelectors.ant("/*"))  // 選擇哪些路徑的API需要生成文檔
                .build();  // 構(gòu)建Docket實(shí)例
    }
    /**
     * 構(gòu)建API基本信息，用于頁面展示的文檔信息。
     *
     * @return ApiInfo對(duì)象，包含相關(guān)API的描述信息
     */
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("")  // 設(shè)置文檔標(biāo)題
                .description(" 測(cè)試swagger")  // 設(shè)置文檔描述信息
                .contact(new Contact("", "git地址", "zhuchb_0509@163.com"))  // 設(shè)置聯(lián)系人信息
                .version("1.0")  // 設(shè)置文檔版本
                .build();  // 構(gòu)建ApiInfo實(shí)例
    }
}

3. 將注釋添加到控制器中

使用 Swagger 注釋描述注冊(cè)到Controller。例如：

package com.ck.framework.user.controller;
import com.ck.framework.common.web.bean.Result;
import com.ck.framework.user.entity.PageResult;
import com.ck.framework.user.entity.dto.UserDto;
import com.ck.framework.user.entity.po.UserPo;
import com.ck.framework.user.entity.req.UserListReq;
import com.ck.framework.user.entity.req.UserReq;
import com.ck.framework.user.service.UserService;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
/**
 * @ClassName UserController
 * @Description
 * @Author 
 * @Date 2024/8/24 0:03
 * @Version 1.0
 */
@RestController
@RequestMapping("/user")
@Api(value = "用戶管理")
public class UserController {
    @Autowired
    private UserService userService;
    @PostMapping
    public Result<Boolean> addUser(@RequestBody UserReq userReq) {
        UserDto userDto = new UserDto();
        userDto.setName(userReq.getName());
        userDto.setAge(userReq.getAge());
        int num = userService.addUser(userDto);
        if (num > 0) {
            return Result.success(true);
        } else {
            return Result.fail();
        }
    }
    @DeleteMapping("/{id}")
    public Result<Boolean> deleteUser(@RequestBody UserReq userReq) {
        UserDto userDto = new UserDto();
        userDto.setId(userReq.getId());
        int num = userService.delUser(userDto);
        if (num > 0) {
            return Result.success(true);
        } else {
            return Result.fail();
        }
    }
    @GetMapping
    public Result<PageResult<UserPo>> getUserPage(@RequestBody UserListReq userListReq) {
        UserDto userDto = new UserDto();
        userDto.setPageIndex(userListReq.getPageIndex());
        userDto.setPageSize(userListReq.getPageSize());
        PageResult<UserPo> pageResult = userService.getUserPage(userDto);
        return Result.success(pageResult);
    }
}

4. 訪問 Swagger UI

啟動(dòng)你的 Spring Boot 應(yīng)用程序后，打開瀏覽器訪問http://localhost:8080/swagger-ui.html，你會(huì)看到自動(dòng)生成的 API 文檔及其用戶界面。

5.優(yōu)點(diǎn)

工具鏈完備:
- Swagger 提供了全面的工具，包括 Swagger Editor、Swagger Codegen 和 Swagger UI，這些工具可以涵蓋從開發(fā)到文檔化的各個(gè)環(huán)節(jié)。
廣泛支持:
- 被多個(gè)語言和框架廣泛支持，幾乎成為業(yè)界標(biāo)準(zhǔn)。
豐富的插件和社區(qū)支持:
- 有大量的插件和擴(kuò)展，可以滿足各種自定義需求。
可視化交互:
- Swagger UI 提供了極為友好的界面，允許開發(fā)者甚至非技術(shù)人員進(jìn)行直接的API測(cè)試與調(diào)用。