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

IT外包达人

3670人浏览 · 2024-07-25 11:23:18

IT外包达人 · 2024-07-25 11:23:18 发布

一、创建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

在这里插入图片描述

魔乐社区

魔乐社区（Modelers.cn) 是一个中立、公益的人工智能社区，提供人工智能工具、模型、数据的托管、展示与应用协同服务，为人工智能开发及爱好者搭建开放的学习交流平台。社区通过理事会方式运作，由全产业链共同建设、共同运营、共同享有，推动国产AI生态繁荣发展。

更多推荐

小参数・大码力・易部署 | Qwen3.6-27B上线魔乐社区，基于昇腾的部署教程来了

继一周前模型开源发布后，千问再度开源Qwen3.6-27B —— 一个拥有270亿参数的稠密多模态模型，也是社区呼声最高的模型规格。Qwen3.6-27B 依然支持多模态思考与非思考模式，在智能体编程方面达到了旗舰级表现，全面超越前代开源旗舰 Qwen3.5-397B-A17B（总参数397B / 激活参数17B的MoE模型）。作为稠密架构，它无需MoE路由即可部署，是开发者在实用、可广泛部署规模