SpringBoot3使用Swagger3的示例詳解

更新時間：2024年11月26日 14:30:28 作者：夜瀾聽雨聲

本文介紹了如何在Spring Boot 3項目中使用Swagger3進行后端接口的前端展示,首先,通過添加依賴并配置application.yml文件來快速啟動Swagger,然后,詳細介紹了Swagger3的新注解與Swagger2的區(qū)別,并提供了一些常用注解的使用示例,感興趣的朋友跟隨小編一起看看吧

項目中的后端接口進行簡單的前端展示

Swagger是一個用于設計、構建、文檔化和使用RESTful Web服務的開源工具。Swagger3是Swagger的最新版本，它提供了許多新功能和改進。

Swagger在SpringBoot3中的引入方法發(fā)生了改變,網(wǎng)上大部分還是SpringBoot2的版本

springboot版本3.2.4

一、依賴引入

用maven構建一個SpringBoot3的項目,在依賴中引入,在pom.xml中添加

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

版本也可以使用新版，Springdoc-OpenAPI網(wǎng)站鏈接

二、快速啟動

1.在application.yml中配置

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

2.或者properties文件,則配置

代碼如下（示例）：

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

3.啟動項目訪問swagger

訪問http://localhost:9090/swagger-ui/index.html#/
其中的9090 改成你項目后端使用的端口，注意不能省略后面的index.html

三、使用注解標注接口

Swagger配置文件

package com.sumo.ipd.config;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class Swagger3Config {
    @Bean
    public OpenAPI springOpenAPI() {
        // 訪問路徑：http://localhost:9090/swagger-ui/index.html
        return new OpenAPI().info(new Info()
                .title("SpringDoc API")
                .description("SpringDoc Simple Application")
                .version("0.0.1"));
    }
}

Swagger 注解遷移

Swagger2 和 Swagger3 使用的是完全不同的兩套注解，所以原本使用 Swagger2 相關注解的代碼頁需要完全遷移，改為使用 Swagger3 的注解。

Swagger2	Swagger3
@Api	@Tag
@ApiOperation	@Operation
@ApiImplicitParams	@Parameters
@ApiImplicitParam	@Parameter
@ApiModel	@Schema
@ApiModelProperty	@Schema
@ApiResponses	@ApiResponses
@ApiResponse	@ApiResponse
@ApiIgnore	@Hidden 或者其他注解的 hidden = true 屬性

舉例五種常用

@Api

Swagger2 代碼

@Api(value = "用戶接口", tags = "UserController")

Swagger3 代碼

@Tag(name = "UserController", description = "用戶接口")

@ApiOperation

Swagger2 代碼

@ApiOperation(value = "查詢用戶數(shù)據(jù)")

Swagger3 代碼

@Operation(description = "查詢用戶數(shù)據(jù)")

@ApiImplicitParam

Swagger2 代碼

@ApiImplicitParams({
     @ApiImplicitParam(name = "currentPage", value = "當前頁碼", dataTypeClass = Integer.class, required = true),
     @ApiImplicitParam(name = "size", value = "當前頁大小", defaultValue = "10", dataTypeClass = Integer.class),
     @ApiImplicitParam(name = "queryUser", value = "用戶查詢條件", dataTypeClass = User.class)
})

Swagger3 代碼

@Parameters({
    @Parameter(name = "currentPage", description = "當前頁碼", required = true),
    @Parameter(name = "size", description = "當前頁大小", example = "10"),
    @Parameter(name = "queryUser", description = "用戶查詢條件")
})

@ApiModel

Swagger2 代碼

@ApiModel(value = "用戶信息實體類")

Swagger3 代碼

@Schema(name = "用戶信息實體類")

@ApiModelProperty

Swagger2 代碼

@ApiModelProperty(value = "用戶名稱")

Swagger3 代碼

@Schema(name = "用戶名稱")

使用示例

package com.sumo.ipd.controller;
import com.sumo.ipd.annotation.BusLog;
import com.sumo.ipd.entity.Department;
import com.sumo.ipd.entity.User;
import com.sumo.ipd.enums.Sex;
import com.sumo.ipd.enums.UserStatus;
import com.sumo.ipd.service.DepartmentService;
import com.sumo.ipd.service.UserService;
import com.sumo.ipd.utils.ExcelUtil;
import com.sumo.ipd.utils.PwdUtil;
import com.sumo.ipd.vo.LoginToken;
import com.sumo.ipd.vo.R;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.Resource;
import jakarta.servlet.http.HttpSession;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import java.util.*;
@RestController
@RequestMapping("user")
@CrossOrigin
@Tag(name = "UserController", description = "用戶接口")
public class UserController {
    @Resource
    UserService userService;
    @Resource
    DepartmentService departmentService;
    /**
     * 用戶注冊
     *
     * @param registerUser
     * @return
     */
    @Operation(description = "用戶注冊")
    @PostMapping("register")
    public R register(@RequestBody User registerUser) {
        if (userService
                .query()
                .eq(User.COL_CERTIFICATENO, registerUser.getCertificateNo())
                .count() > 0) {
            return R.builder().code(0).message("用戶已存在！").build();
        } else {
            userService.save(registerUser);
            return R.builder().code(200).message("注冊成功！請等待組織管理員審核...").build();
        }
    }
}

到此這篇關于SpringBoot3使用Swagger3的文章就介紹到這了,更多相關SpringBoot3使用Swagger3內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: