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

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

【Springboot整合Swagger3全注解配置(springdoc-openapi-ui)】
一、创建Springboot项目，引入pom依赖

org.springframework.bootspring-boot-starter-weborg.springframework.bootspring-boot-starter-testtestorg.projectlomboklombok1.18.12org.springdocspringdoc-openapi-ui1.5.5

二、配置类请求头携带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: 8080springdoc:api-docs:#是否开启文档功能enabled: true#swagger后端请求地址path: /api-docsswagger-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 addUser(String name); @Operation(summary = "管理员删除用户", description = "根据姓名删除用户")@ApiResponse(description = "返回添加的用户", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class)))CommonResult delUser(@Parameter(description = "姓名") String name); @Operation(summary = "管理员更新用户", description = "管理员根据姓名更新用户")@ApiResponse(description = "返回更新的用户", content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class)))CommonResult 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")@Slf4jpublic class AdminController implements AdminControllerApi {@PostMapping("/add/{name}")@Overridepublic CommonResult addUser(@PathVariable String name) {return CommonResult.success(new User(name, 18)); }@GetMapping("/del/{name}")@Overridepublic CommonResult delUser(@PathVariable String name) {log.info("管理员删除name={}的用户", name); return CommonResult.success(new User(name, 25)); }@PostMapping("/update")@Overridepublic CommonResult 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")@Slf4jpublic class UserController implements UserControllerApi {@PostMapping("/add/{name}")@Overridepublic User addUser(@PathVariable String name) {return new User(name, 18); }@GetMapping("/del/{name}")@Overridepublic 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 {@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 CommonResult success(T data) {return new CommonResult(200, "操作成功", data); }/*** 失败返回结果** @param message 提示信息*/public static CommonResult failed(String message) {return new CommonResult(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@AllArgsConstructorpublic class User {@Schema(name = "name",description = "姓名")private String name; @Schema(name = "age",description = "年龄")private int age; }

七、运行项目查看效果浏览器输入127.0.0.1:8080/test会重定向到swagger页面