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

目录
  • 一、创建Springboot项目,引入pom依赖
  • 二、配置类请求头携带token
  • 三、配置文件
  • 四、接口定义
  • 五、实现类
  • 六、实体类定义
  • 七、运行项目查看效果

一、创建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全注解配置内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • 关于springboot集成swagger3时spring-plugin-core报错的问题

    springboot集成knife4j的时候3.0.2版本出现了以下问题: An attempt was made to call a method that does not exist. The attempt was made from the following location:       springfox.documentation.schema.plugins.SchemaPluginsManager.viewProvider(SchemaPluginsManager.java

  • springboot2.6.4集成swagger3.0遇到的坑及解决方法

    Swagger简介 号称:世界上最流行的API框架 PestFul API文档在线自动生成器 --> API文档与API定义同步更新可以直接运行,测试API接口 支持多种语言 强调:我的springboot版本2.6.4,swagger为3.0,其他版本可能修改不成功,大家可以试试. 在集成的时候出现了很多问题 坑一:首先先排除问题 ,我使用的springboot版本2.6.4,导入的swagger依赖如下 <dependency> <groupId>io.springfox

  • SpringBoot集成Swagger3的实现

    目录 一,什么是swagger? 二,SpringBoot 集成swagger3 三,swagger3 注解标签使用 一,什么是swagger? 1,  Swagger 是一个规范和完整的文档框架,     用于生成.描述.调用和可视化 RESTful 风格的 Web 服务文档     官方网站:https://swagger.io/ 2,使用swagger要注意的地方:      在生产环境中必须关闭swagger,      它本身只用于前后端工程师之间的沟通,      可以专门使用一台内

  • SpringBoot整合Swagger3生成接口文档过程解析

    前后端分离的项目,接口文档的存在十分重要.与手动编写接口文档不同,swagger是一个自动生成接口文档的工具,在需求不断变更的环境下,手动编写文档的效率实在太低.与新版的swagger3相比swagger2配置更少,使用更加方便. 一.pom文件中引入Swagger3依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId

  • springboot更新配置Swagger3的一些小技巧

    1.引入依赖,版本3.0.0只引入一个即可 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> 2. 配置类SwaggerConfig package org.fh.config; import org

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

    目录 一.创建Springboot项目,引入pom依赖 二.配置类请求头携带token 三.配置文件 四.接口定义 五.实现类 六.实体类定义 七.运行项目查看效果 一.创建Springboot项目,引入pom依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </depend

  • springboot整合mybatis-plus基于注解实现一对一(一对多)查询功能

    因为目前所用mybatis-plus版本为3.1.1,感觉是个半成品,所有在实体类上的注解只能支持单表,没有一对一和一对多关系映射,且该功能还在开发中,相信mybatis-plus开发团队在不久的将来应该会实现此功能. 由于本人开发习惯的原因,实在是太讨厌大量的xml充斥在整个项目中,尤其是表的mapper.xml,虽然有代码生成器可以生成,但是有些复杂的查询还是需要手写配置文件里的动态sql,这点比较反感(至于为什么反感,也是有多方面原因的). 不过可能是大量的java开发人员已经被虐惯了,已

  • 聊聊SpringBoot整合Nacos自动刷新配置的问题

    目录 目的 环境 pom 配置文件 代码 日志 测试 目的 Nacos作为SpringBoot服务的注册中心和配置中心. 在NacosServer中修改配置文件,在SpringBoot不重启的情况下,获取到修改的内容. 本例将在配置文件中配置一个 cml.age=100 的配置项,程序中编写一个方法读取配置文件,并通过 Get--->/test/age 接口提供给浏览器访问. 若配置文件中的 age 修改为 200 ,不用重新启动程序,直接访问 /test/age 接口,将获取到最新的值 200

  • SpringBoot整合Web之AOP配置详解

    目录 配置AOP AOP简介 Spring Boot 支持 其它 自定义欢迎页 自定义 favicon 除去某个自动配置 配置AOP AOP简介 要介绍面向切面变成(Aspect-Oriented Programming,AOP),需要先考虑一个这样的场景:公司有一个人力资源管理系统目前已经上线,但是系统运行不稳定,有时运行的很慢,为了检测到底是哪个环节出现问题了,开发人员想要监控每一个方法执行的时间,再根据这些执行时间判断出问题所在.当问题解决后,再把这些监控移除掉.系统目前已经运行,如果手动

  • springboot整合mybatis-plus代码生成器的配置解析

    AutoGenerator 是 MyBatis-Plus 的代码生成器,通过 AutoGenerator 可以快速生成 Entity.Mapper.Mapper XML.Service.Controller 等各个模块的代码,极大的提升了开发效率. 具体实实现以及配置解析如下: package mybatis_plus; import com.baomidou.mybatisplus.annotation.DbType; import com.baomidou.mybatisplus.annot

  • SpringBoot整合Mybatis,解决TypeAliases配置失败的问题

    问题描述 在应用MyBatis时,使用对象关系映射,将对象和Aliase映射起来. 在Mybatis的文档明确写出,如果你没有明确定义实体类的Aliase,框架会自动将Class Name自动作为别名. 那么问题来了,当使用java -jar xxx.jar&启动的时候,会报出以下错误, Error resolving class. Cause: org.apache.ibatis.type.TypeException: Could not resolve type alias 'XXXXX'.

  • springboot整合Quartz实现动态配置定时任务的方法

    前言 在我们日常的开发中,很多时候,定时任务都不是写死的,而是写到数据库中,从而实现定时任务的动态配置,下面就通过一个简单的示例,来实现这个功能. 一.新建一个springboot工程,并添加依赖 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency

  • SpringBoot整合Apollo配置中心快速使用详解

    目录 一.简介 二.使用 1. 测试项目搭建 2. Apollo配置中心的配置 3. 项目启动与测试 4.常见整合问题 附录 一.简介 1.Apollo 是什么?Apollo(阿波罗)是携程框架部门研发的分布式配置中心.服务端基于Spring Boot和Spring Cloud开发. 2.为什么要使用Apollo? 安全性:配置跟随源代码保存在代码库中,容易造成配置泄漏 时效性:普通方式配置,修改配置,需要重启服务才能生效 局限性:无法支持动态调整:例如日志开关.功能开关 二.使用 1. 测试项

  • Springboot整合Redis与数据持久化

    目录 Springboot整合Redis 使用json方式存储 序列化方式存储数据 MySQL与Redis一致性解决同步问题 Redis持久化机制 全量同步与增量同步 RDB与AOF RDB AOF Springboot整合Redis 有两种存储数据的方式: 方案1:在Redis存放一个对象 使用json序列化与反序列化 方案2:直接使用redis自带序列化方式存储对象 maven依赖 <parent> <groupId>org.springframework.boot</g

随机推荐