脚本之家 服务器常用软件
快捷导航
您的位置：首页 → 软件编程 → java → Springboot Swagger3全注解配置

Springboot整合Swagger3全注解配置(springdoc-openapi-ui)

 更新时间：2022年03月14日 11:16:04   作者：阿祖，收手吧  
本文主要介绍了Springboot整合Swagger3全注解配置(springdoc-openapi-ui)，文中通过示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下

一、创建Springboot项目，引入pom依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.12</version>
        </dependency>

        <!-- 只需要引入这一个依赖就行了 -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.5.5</version>
        </dependency>

二、配置类请求头携带token

import io.swagger.v3.oas.annotations.ExternalDocumentation;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeIn;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;

@OpenAPIDefinition(
        info = @Info(
                title = "Swagger3",
                version = "1.0",
                description = "Swagger3使用演示",
                contact = @Contact(name = "TOM")
        ),
        security = @SecurityRequirement(name = "JWT"),
        externalDocs = @ExternalDocumentation(description = "参考文档",
                url = "https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations"
        )
)
@SecurityScheme(type = SecuritySchemeType.HTTP, name = "JWT", scheme = "bearer", in = SecuritySchemeIn.HEADER)
public class Swagger3Config {

}
  • @OpenAPIDefinition全局只能定义一个，主要配置文档信息和安全配置，这里列举了常用的请求头携带token的安全配置模式
  • @OpenAPIDefinition下的info属性配置文档信息
  • @OpenAPIDefinition下的security配置认证方式，name属性引入自定义的认证模式
  • @SecurityScheme注解就是自定义的认证模式，配置请求头携带token

三、配置文件

server:
  port: 8080

springdoc:
  api-docs:
    #是否开启文档功能
    enabled: true
    #swagger后端请求地址
    path: /api-docs
  swagger-ui:
    #自定义swagger前端请求路径，输入http：127.0.0.1:8080/test会自动重定向到swagger页面
    path: /test
  #包扫描路径
  packages-to-scan: com.hello.controller,com.hello.dto
  #这里定义了两个分组，可定义多个，也可以不定义
  group-configs:
      #分组名
    - group: admin
      #按路径匹配
      pathsToMatch: /admin/**
      #分组名
    - group: user
      #按包路径匹配
      packagesToScan: com.hello.api.user

四、接口定义

定义两个接口

package com.hello.api.admin;

import com.hello.dto.CommonResult;
import com.hello.dto.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "AdminControllerApi", description = "管理员相关接口")
public interface AdminControllerApi {

    @Operation(summary = "管理员添加用户",
            description = "根据姓名添加用户并返回",
            parameters = {
                    @Parameter(name = "name", description = "姓名")
            },
            responses = {
                    @ApiResponse(description = "返回添加的用户", content = @Content(mediaType = "application/json", schema = @Schema(anyOf = {CommonResult.class, User.class}))),
                    @ApiResponse(responseCode = "400", description = "返回400时候错误的原因")
            }
    )
    CommonResult<User> addUser(String name);

    @Operation(summary = "管理员删除用户", description = "根据姓名删除用户")
    @ApiResponse(description = "返回添加的用户", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class)))
    CommonResult<User> delUser(@Parameter(description = "姓名") String name);


    @Operation(summary = "管理员更新用户", description = "管理员根据姓名更新用户")
    @ApiResponse(description = "返回更新的用户", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class)))
    CommonResult<User> updateUser(@Parameter(schema = @Schema(implementation = User.class), required = true, description = "用户类") User user);
}



package com.hello.api.user;

import com.hello.dto.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "UserControllerApi", description = "用户的增删改查")
public interface UserControllerApi {

    @Operation(summary = "添加用户",
            description = "根据姓名添加用户并返回",
            parameters = {
                    @Parameter(name = "name", description = "姓名")
            },
            responses = {
                    @ApiResponse(description = "返回添加的用户",
                            content = @Content(mediaType = "application/json",
                                    schema = @Schema(implementation = User.class))),
                    @ApiResponse(responseCode = "400", description = "返回400时候错误的原因")}
    )
    User addUser(String name);

    @Operation(summary = "删除用户",
            description = "根据姓名删除用户",
            parameters = {
                    @Parameter(name = "name", description = "姓名")
            })
    void delUser(String name);
}

五、实现类

实现刚才的两个接口

package com.hello.controller.admin;

import com.hello.api.admin.AdminControllerApi;
import com.hello.dto.CommonResult;
import com.hello.dto.User;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/admin")
@Slf4j
public class AdminController implements AdminControllerApi {

    @PostMapping("/add/{name}")
    @Override
    public CommonResult<User> addUser(@PathVariable String name) {
        return CommonResult.success(new User(name, 18));
    }

    @GetMapping("/del/{name}")
    @Override
    public CommonResult<User> delUser(@PathVariable String name) {
        log.info("管理员删除name={}的用户", name);
        return CommonResult.success(new User(name, 25));
    }

    @PostMapping("/update")
    @Override
    public CommonResult<User> updateUser(@RequestBody User user) {
        user.setAge(100);
        log.info("管理员更新{}用户的年龄为{}", user, 100);
        return CommonResult.success(user);
    }
}


package com.hello.controller.user;

import com.hello.api.user.UserControllerApi;
import com.hello.dto.User;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/user")
@Slf4j
public class UserController implements UserControllerApi {

    @PostMapping("/add/{name}")
    @Override
    public User addUser(@PathVariable String name) {
        return new User(name, 18);
    }

    @GetMapping("/del/{name}")
    @Override
    public void delUser(@PathVariable String name) {
        log.info("删除name={}的用户", name);
    }
}

六、实体类定义

package com.hello.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@AllArgsConstructor
@Schema(name = "CommonResult", description = "通用返回对象")
public class CommonResult<T> {
    @Schema(name = "code", description = "状态码")
    private long code;

    @Schema(name = "message", description = "提示信息")
    private String message;

    @Schema(name = "data", description = "数据封装")
    private T data;

    /**
     * 成功返回结果
     *
     * @param data 获取的数据
     */
    public static <T> CommonResult<T> success(T data) {
        return new CommonResult<T>(200, "操作成功", data);
    }

    /**
     * 失败返回结果
     *
     * @param message 提示信息
     */
    public static <T> CommonResult<T> failed(String message) {
        return new CommonResult<T>(400, message, null);
    }
}

package com.hello.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;

@Schema(name="User",description ="用户信息" )
@Data
@AllArgsConstructor
public class User {
    @Schema(name = "name",description = "姓名")
    private String name;
    @Schema(name = "age",description = "年龄")
    private int age;
}

七、运行项目查看效果

浏览器输入127.0.0.1:8080/test会重定向到swagger页面

在这里插入图片描述

在这里插入图片描述

在这里插入图片描述

点击右上角的Authorize就会弹出以下界面，输入token，请求接口就会自动携带该token发送请求，这里随便输入一个abc为token，点击Authorize

在这里插入图片描述

在这里插入图片描述

打开一个接口去测试，查看效果，发现请求已经自动携带了token

在这里插入图片描述

 到此这篇关于Springboot整合Swagger3全注解配置(springdoc-openapi-ui)的文章就介绍到这了,更多相关Springboot Swagger3全注解配置内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

相关文章

  • Java 3种方法实现进制转换

    Java 3种方法实现进制转换

    这篇文章主要介绍了Java 3种方法实现进制转换，帮助大家利用Java处理数据，感兴趣的朋友可以了解下
    2020-09-09
  • Java设计模式中的单一责任原则详解

    Java设计模式中的单一责任原则详解

    这篇文章主要介绍了Java设计模式中的单一责任原则详解,应该有且仅有一个原因引起类的变更,即单一指责原则要求一个借口或类只有一个原因引起变化,也就是一个接口或类只有一个职责,它就负责一件事情,需要的朋友可以参考下
    2023-11-11
  • 使用Java桥接模式打破继承束缚优雅实现多维度变化

    使用Java桥接模式打破继承束缚优雅实现多维度变化

    这篇文章主要为大家介绍了使用Java桥接模式打破继承束缚，优雅实现多维度变化，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪
    2023-05-05
  • MyBatis方法重载的陷阱及解决方案

    MyBatis方法重载的陷阱及解决方案

    在使用 MyBatis 进行开发时,尤其是使用注解模式（如 @Select、@Insert 等）时,开发者常常会遇到这样一个问题：为什么我的方法重载不能正常工作？这篇文章将深入探讨 MyBatis 的这个特性及如何规避相关的坑,需要的朋友可以参考下
    2024-09-09
  • 基于ElasticSearch Analyzer的使用规则详解

    基于ElasticSearch Analyzer的使用规则详解

    这篇文章主要介绍了基于ElasticSearch Analyzer的使用规则，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
    2021-07-07
  • 全面解析Spring Security 过滤器链的机制和特性

    全面解析Spring Security 过滤器链的机制和特性

    这篇文章主要介绍了Spring Security 过滤器链的机制和特性,本文给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下
    2020-07-07
  • 使用MultipartFile来上传单个及多个文件代码示例

    使用MultipartFile来上传单个及多个文件代码示例

    这篇文章主要介绍了使用MultipartFile来上传单个及多个文件代码示例,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
    2024-01-01
  • 详解JAVA的控制语句

    详解JAVA的控制语句

    这篇文章主要介绍了Java中的控制语句,循环等语句是Java编程中流程控制的基础,需要的朋友可以参考下，希望能够给你带来帮助
    2021-11-11
  • IDEA设置Maven自动编译model的实现方法

    IDEA设置Maven自动编译model的实现方法

    本文主要介绍了IDEA设置Maven自动编译model的实现方法, maven结构的项目,我们在每次修改代码后都会需要手动编译,本文就可以解决这个问题,感兴趣的可以了解一下
    2023-08-08
  • java中hibernate二级缓存详解

    java中hibernate二级缓存详解

    本篇文章中主要介绍了java中hibernate二级缓存详解，小编觉得挺不错的，现在分享给大家，也给大家做个参考。一起跟随小编过来看看吧
    2017-05-05

最新评论