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

更新時間：2022年03月14日 11:16:04 作者：阿祖，收手吧

本文主要介紹了Springboot整合Swagger3全注解配置(springdoc-openapi-ui)，文中通過示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下

一、創(chuàng)建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 = "狀態(tài)碼")
    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發(fā)送請求，這里隨便輸入一個abc為token，點擊Authorize

在這里插入圖片描述

打開一個接口去測試，查看效果，發(fā)現請求已經自動攜帶了token

在這里插入圖片描述

到此這篇關于Springboot整合Swagger3全注解配置(springdoc-openapi-ui)的文章就介紹到這了,更多相關Springboot Swagger3全注解配置內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

您可能感興趣的文章:

數組重排序(如何將所有奇數都放在所有偶數前面)的深入分析
本篇文章是對數組重排序(如何將所有奇數都放在所有偶數前面)的方法進行了詳細的分析介紹，需要的朋友參考下
2013-06-06
Java服務端如何解決跨域問題?CORS請求頭方式
這篇文章主要介紹了Java服務端如何解決跨域問題?CORS請求頭方式，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教
2022-11-11
淺談Java利用表格模型創(chuàng)建表格
這篇文章主要介紹了Java利用表格模型創(chuàng)建表格,需要的朋友可以參考下
2017-09-09
Java實現抽獎功能
這篇文章主要為大家詳細介紹了Java實現抽獎功能，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下
2020-11-11
java性能分析jconsole詳解
這篇文章主要介紹了java性能分析jconsole詳解，文章圍繞主題展開詳細的內容介紹，具有一定的參考價值，需要的小伙伴可以參考一下
2022-07-07
Spring中@DependsOn注解的作用及實現原理解析
這篇文章主要介紹了Spring中@DependsOn注解的作用及實現原理解析,本文給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下
2021-03-03
java猜數字小游戲案例
這篇文章主要為大家詳細介紹了java猜數字小游戲案例，文中示例代碼介紹的非常詳細，具有一定的參考價值，感興趣的小伙伴們可以參考一下
2019-10-10
Java中的main方法調用非靜態(tài)方法處理
這篇文章主要介紹了Java中的main方法調用非靜態(tài)方法處理，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教
2023-06-06
解決Maven 項目報錯 java.httpservlet和synchronized使用方法
下面小編就為大家?guī)硪黄鉀QMaven 項目報錯 java.httpservlet和synchronized使用方法。小編覺得挺不錯的，現在就分享給大家，也給大家做個參考。一起跟隨小編過來看看吧
2017-07-07
java簡單快速排序實例解析
這篇文章主要為大家詳細介紹了java簡單快速排序實例，具有一定的參考價值，感興趣的小伙伴們可以參考一下
2017-08-08