当前位置:   article > 正文

SpringBoot3使用Swagger3_springboot3 swagger

springboot3 swagger


项目中的后端接口进行简单的前端展示

Swagger是一个用于设计、构建、文档化和使用RESTful Web服务的开源工具。Swagger3是Swagger的最新版本,它提供了许多新功能和改进。

Swagger在SpringBoot3中的引入方法发生了改变,网上大部分还是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>
  • 1
  • 2
  • 3
  • 4
  • 5

版本也可以使用新版,Springdoc-OpenAPI网站链接

二、快速启动

1.在application.yml中配置

# swagger-ui custom path
springdoc:
  swagger-ui:
    path : /swagger-ui.html
  • 1
  • 2
  • 3
  • 4

2.或者properties文件,则配置

代码如下(示例):

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html
  • 1
  • 2

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"));
    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18

Swagger 注解迁移

Swagger2 和 Swagger3 使用的是完全不同的两套注解,所以原本使用 Swagger2 相关注解的代码页需要完全迁移,改为使用 Swagger3 的注解。

Swagger2Swagger3
@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")
  • 1

Swagger3 代码

@Tag(name = "UserController", description = "用户接口")
  • 1

@ApiOperation

Swagger2 代码

@ApiOperation(value = "查询用户数据")
  • 1

Swagger3 代码

@Operation(description = "查询用户数据")
  • 1

@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)
})
  • 1
  • 2
  • 3
  • 4
  • 5

Swagger3 代码

@Parameters({
    @Parameter(name = "currentPage", description = "当前页码", required = true),
    @Parameter(name = "size", description = "当前页大小", example = "10"),
    @Parameter(name = "queryUser", description = "用户查询条件")
})
  • 1
  • 2
  • 3
  • 4
  • 5

@ApiModel

Swagger2 代码

@ApiModel(value = "用户信息实体类")
  • 1

Swagger3 代码

@Schema(name = "用户信息实体类")
  • 1

@ApiModelProperty

Swagger2 代码

@ApiModelProperty(value = "用户名称")
  • 1

Swagger3 代码

@Schema(name = "用户名称")
  • 1

使用示例

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();
        }
    }
}
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
  • 42
  • 43
  • 44
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
  • 53
  • 54
声明:本文内容由网友自发贡献,不代表【wpsshop博客】立场,版权归原作者所有,本站不承担相应法律责任。如您发现有侵权的内容,请联系我们。转载请注明出处:https://www.wpsshop.cn/w/煮酒与君饮/article/detail/939947
推荐阅读
  

闽ICP备14008679号