Springboot整合Swagger3全注解配置(springdoc

Springboot整合Swagger3全注解配置(springdoc

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

一、创建Springboot项目，引入pom依赖

org.springframework.boot

spring-boot-starter-web

org.springframework.boot

spring-boot-starter-test

test

org.projectlombok

lombok

1.18.12

org.springdoc

springdoc-openapi-ui

1.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: 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 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")

@Slf4j

public class AdminController implements AdminControllerApi {

@PostMapping("/add/{name}")

@Override

public CommonResult addUser(@PathVariable String name) {

return CommonResult.success(new User(name, 18));

}

@GetMapping("/del/{name}")

@Override

public CommonResult delUser(@PathVariable String name) {

log.info("管理员删除name={}的用户", name);

return CommonResult.success(new User(name, 25));

}

@PostMapping("/update")

@Override

public 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")

@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 {

@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 Commohttp://nResult 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

@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

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。