SpringDoc和Swagger使用示例詳解

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

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

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

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

一、SpringDoc

Springdoc是一個開源的庫，旨在將Spring Boot項目的RESTful API與OpenAPI 3文檔生成器集成。Springdoc與Spring Boot應用無縫集成，并支持包括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.配置代碼

添加一個配置類，并添加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 文檔的訪問路徑。

默認值:/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 的訪問路徑。
默認值:/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
作用: 定義如何對 Swagger UI 中的操作進行排序。
可選值:
- alpha: 按照操作名稱的字母順序排列。
- method: 按照 HTTP 方法進行排序（如 GET, POST, PUT, DELETE）。
示例:

springdoc:
  swagger-ui:
    operationsSorter: method

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

（4）springdoc.swagger-ui.tagsSorter

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

springdoc:
  swagger-ui:
    tagsSorter: alpha

配置后，標簽會按照字母順序顯示。

（5）springdoc.title

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

springdoc:
  title: 用戶管理

配置后，生成的 API 文檔的標題會顯示為“用戶管理”。

使用

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)點

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

6.缺點

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

二、swagger

Swagger是一個用于生成、描述、調(diào)用和可視化 RESTful Web 服務的開源框架。它的核心是一個名為 OpenAPI 規(guī)范的描述性語言。Swagger 是 Java 應用程序中常用的工具之一，因為它能自動生成 API 文檔，并提供一個用戶友好的接口來測試 API。

在 Java 項目中使用 Swagger 通常包括以下步驟：

1. 添加依賴項

首先，你需要在你的項目中添加所需的 Swagger 依賴項。以 Maven 項目為例，在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

添加一個 Swagger 配置類。例如，在 Spring Boot 應用程序中，你可以添加以下內(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  // 表示這是一個配置類
@EnableSwagger2  // 啟用Swagger2
public class SwaggerConfig {
    /**
     * 創(chuàng)建一個Docket Bean，用于配置Swagger的核心內(nèi)容，包括哪些包中的API需要生成文檔和API的基本信息。
     *
     * @return Docket對象，用于Swagger的配置
     */
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)  // 指定文檔類型為Swagger2
                .apiInfo(apiInfo())  // 配置API信息
                .select()  // 返回一個ApiSelectorBuilder實例，用于控制哪些接口暴露給swagger
                .apis(RequestHandlerSelectors.basePackage("com.ck.framework.common.swagger"))  // 選擇掃描的包名
                .paths(PathSelectors.ant("/*"))  // 選擇哪些路徑的API需要生成文檔
                .build();  // 構(gòu)建Docket實例
    }
    /**
     * 構(gòu)建API基本信息，用于頁面展示的文檔信息。
     *
     * @return ApiInfo對象，包含相關(guān)API的描述信息
     */
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("")  // 設(shè)置文檔標題
                .description(" 測試swagger")  // 設(shè)置文檔描述信息
                .contact(new Contact("", "git地址", "zhuchb_0509@163.com"))  // 設(shè)置聯(lián)系人信息
                .version("1.0")  // 設(shè)置文檔版本
                .build();  // 構(gòu)建ApiInfo實例
    }
}

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

使用 Swagger 注釋描述注冊到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

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

5.優(yōu)點

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

6.缺點

集成復雜:
- 對于部分框架或語言，需要較多的配置和集成工作。
注解依賴:
- 在某些實現(xiàn)中，需要開發(fā)者在代碼中添加大量的注解，增加了代碼復雜性。

到此這篇關(guān)于SpringDoc和Swagger使用示例詳解的文章就介紹到這了,更多相關(guān)SpringDoc和Swagger使用內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章:

最新国产好看的视频,伊人天堂AV在线,国产Aaaaaa视频,蜜臀视频在线观看一区,人妻av色图,密臀久久久精品影片,青青视频免费观看毛片,久草在线观看视,国产三级精品色情在线

SpringDoc和Swagger使用示例詳解

目錄

一、SpringDoc

1.添加依賴

2.配置代碼

3.控制器處理

4.訪問

5.優(yōu)點

6.缺點

二、swagger

1. 添加依賴項

2. 配置 Swagger

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

4. 訪問 Swagger UI

5.優(yōu)點

6.缺點

相關(guān)文章

最新評論

大家感興趣的內(nèi)容

最近更新的內(nèi)容

常用在線小工具

最新国产好看的视频,伊人天堂AV在线,国产Aaaaaa视频,蜜臀视频在线观看一区,人妻av色图,密臀久久久精品影片,青青视频免费观看毛片,久草在线观看视,国产三级精品色情在线

SpringDoc和Swagger使用示例詳解

目錄

一、SpringDoc

1.添加依賴

2.配置代碼

3.控制器處理

4.訪問

5.優(yōu)點

6.缺點

二、swagger

1. 添加依賴項

2. 配置 Swagger

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

4. 訪問 Swagger UI

5.優(yōu)點

6.缺點

相關(guān)文章

最新評論

大家感興趣的內(nèi)容

最近更新的內(nèi)容

常用在線小工具

一、SpringDoc