一、创建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
 
@SpringBootConfiguration
@OpenAPIDefinition(info = @Info(title = "API", version = "v1"))
@SecurityScheme(
        name = "token",
        type = SecuritySchemeType.HTTP,
        bearerFormat = "JWT",
                                    swagger是我们开发过程中非常常用的一个api 文档维护组织吗，为了前后端更好的交互，swagger早已经成为了大家的首选api 文档框架。但随着spring的发展与强大，spring也出了自己的api框架，但实用惯了swagger的用户，在切换过来后发现就不太会用了，其实springdoc本身已经集成并兼容了swagger,但对应的注解有所变化。下面我们就来看看swagger的注解在springdoc中的对应关系。
springdoc的maven依赖
   <dependency>
                                    spring常见注解方法，小编主要结合老师的讲解，和自己的理解方式作为解析，方便后期的记忆。
创建一个学生的实体类
    private String student_id;// 学生id
	private String name;// 学生名字
	// 引用老师对象 每个学生都有一个对应的辅导员
	private Teacher teacher;
	省略get、set、toString方法，自己去生成。
创建一个老师的实体类
    private String teacher_id;// 教师编号
                                    1.xml文件中的spring注解约束
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/
                                    很多从 swagger 2 过来的用户可能会好奇，为什么不使用 springfox 库来生成 API，我在这里简单总结一下springdoc-openapi 是 spring 官方出品，与 springboot 兼容更好（springfox 兼容有坑）springdoc-openapi 社区更活跃，springfox 已经 2 年没更新了springdoc-openapi 的注解更接近 OpenAPI 3 规范。
                                    这里为什么要使用SpringDoc呢？是因为集成SpringFox只支持SpringBoot2.x，而基于Swagger的SpringDoc的社区现在十分活跃，代码也在不断更新。SpringFox自从2020年7月14号之后就不更新了。
                                    java库有助于使用 spring boot 项目自动生成 API 文档。通过在运行时检查应用程序以根据 spring 配置、类结构和各种注释推断 API 语义来工作。自动生成 JSON/YAML 和 HTML 格式 API 的文档。可以使用 swagger-api 注释通过注释来完成此文档。OpenAPI3Swagger-uiOAuth 2GraalVM 原生镜像Knife4j是一个集Swagger2和OpenAPI3为一体的增强解决方案。