当前位置：首页 > news >正文

微服务项目-＞在线oj系统(Java-Spring)----3.0

news 2025/9/20 12:56:59

接口文档

简介

接⼝⽂档，顾名思义就是接⼝的说明⽂档，它是我们调⽤接⼝的依据。

作用

• 简化前端开发：前端开发者⽆需担⼼不同接⼝返回不同格式的数据，他们可以编写统⼀的解析逻辑来处理响应。
• 易于错误处理：接⼝⽂档定义统⼀的响应格式包括⼀个状态码或错误字段，⽤于指⽰请求是否成功以及可能的错误原因。这简化了错误处理逻辑，并允许客⼾端更容易地识别和处理错误
• 代码可维护性：遵循统⼀的格式意味着代码更加⼀致，这有助于减少错误并提⾼代码的可维护性。当其他开发者接⼿项⽬时，他们不需要学习多种不同的响应格式。
• ⽂档化：统⼀的响应格式可以更容易地⽂档化，因为你可以为整个项⽬创建⼀个通⽤的API⽂档模板。

内容

接口概述
包括接⼝名称、接⼝功能、接⼝类别等。
接口地址
接⼝的唯⼀访问地址：127.0.0.1:8080/sysUser/login
请求方法
定义接⼝的请求⽅式，如GET（查询）、POST（新增）、PUT（修改）、DELETE
请求参数
定义请求时需要传递的参数，包括路径参数（Path Parameters）、查询参数（Query
Parameters）、请求头（Headers）、请求体（Body）
响应数据
定义接⼝返回的数据格式，包括状态码（Status Code）、消息（Message）、数据体 (Data)
请求和响应示例
为了更好地描述接⼝的使⽤，接⼝⽂档中会提供⼀些具体的接⼝请求和响应⽰
例，以供读者参考。

响应数据定义

@Data
public class R <T>{private T data;private String msg;private int code;
}

状态码定义

但是这些状态码有时不能完全⽀撑我们的业务我们有时希望通过状态码说明更加详细的信息，另⼀⽅⾯处于安全考虑当服务器出错时我们不直接暴露底层的系统错误。

自定义状态码

在 com.bite.common.core.enums 包下创建枚举类型命名为ResultCode

@AllArgsConstructor
@Getter
public enum ResultCode {//操作成功SUCCESS                         (1000, "操作成功"),//服务器内部错误，友好提示ERROR                           (2000, "服务繁忙请稍后重试"),//操作失败，但是服务器不存在异常FAILED                          (3000, "操作失败"),FAILED_UNAUTHORIZED             (3001, "未授权"),FAILED_PARAMS_VALIDATE          (3002, "参数校验失败"),FAILED_NOT_EXISTS               (3003, "资源不存在"),FAILED_ALREADY_EXISTS           (3004, "资源已存在"),FAILED_USER_EXISTS              (3101, "用户已存在"),FAILED_USER_NOT_EXISTS          (3102, "用户不存在"),FAILED_LOGIN                    (3103, "用户名或密码错误"),FAILED_USER_BANNED              (3104, "您已被列入黑名单，请联系管理员.");/*** 状态码*/private int code;/*** 状态描述*/private String msg;
}

使用方法：

引入Swagger

Swagger是⼀个接⼝⽂档⽣成⼯具，它可以帮助开发者⾃动⽣成接⼝⽂档。当项⽬的接⼝发⽣变更时，Swagger可以实时更新⽂档，确保⽂档的准确性和时效性。Swagger还内置了测试功能，开发者可以直接在⽂档中测试接⼝，⽆需编写额外的测试代码。

1.在oj-common下创建,oj-common-swagger⼦module

2.导入依赖

 <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>${springdoc-openapi.version}</version></dependency>

3.录⼊配置

@Configuration
public class SwaggerConfig {@Beanpublic OpenAPI openAPI(){return new OpenAPI().info(new Info().title("在线OJ系统").description("在线OJ系统接口文档").version("v1"));}
}

4.创建org.springframework.boot.autoconfigure.AutoConfiguration.imports⽂件

com.bite.common.swagger.SwaggerConfig

为什么要有这步呢？

因为我们在上面SwaggerConfig里面使用的Bean对象，但是其他服务的Spring扫描的时候无法扫描到，所以，我们需要添加这个文件，使Bean被其他服务的SPringle扫描到

注意：

这里的目录结构很重要，如果结构不对，那么也不会启效果

5.具体服务引⼊:

其他要服务使用Swagger的需要引入依赖

<dependency><groupId>com.bite</groupId><artifactId>oj-common-swagger</artifactId><version>${oj-common-swagger.version}</version><scope>compile</scope></dependency>

使用Swagger示例

@RestController
@RequestMapping("sysUser")
@Tag(name = "管理员接口")
public class SysUserController {@Autowiredprivate ISysUserService sysUserService;@PostMapping("login")@Operation(summary = "管理员登录", description = "根据账号密码进行管理员登录")@ApiResponse(responseCode = "1000", description = "操作成功")@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")@ApiResponse(responseCode = "3102", description = "用户不存在")@ApiResponse(responseCode = "3103", description = "用户名或密码错误")public R<Void> login(@RequestBody LoginDTO loginDTO){return  sysUserService.login(loginDTO.getUserAccount(),loginDTO.getPassword());}@Operation(summary = "新增管理员", description = "根据提供的信息新增管理员⽤⼾")@ApiResponse(responseCode = "1000", description = "操作成功")@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")@ApiResponse(responseCode = "3101", description = "⽤⼾已存在")@PostMapping("/add")public R<Void> add(@RequestBody SysUserSaveDTO saveDTO) {return null;}@DeleteMapping("/{userId}")@Operation(summary = "删除用户", description = "通过用户id删除用户")@Parameters(value = {@Parameter(name = "userId", in = ParameterIn.PATH, description = "用户ID")})@ApiResponse(responseCode = "1000", description = "成功删除用户")@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")@ApiResponse(responseCode = "3101", description = "用户不存在")public R<Void> delete(@PathVariable Long userId) {return null;}@Operation(summary = "用户详情", description = "根据查询条件查询用户详情")@GetMapping("/detail")@Parameters(value = {@Parameter(name = "userId", in = ParameterIn.QUERY, description = "用户ID"),@Parameter(name = "sex", in = ParameterIn.QUERY, description = "用户性别")})@ApiResponse(responseCode = "1000", description = "成功获取用户信息")@ApiResponse(responseCode = "2000", description = "服务繁忙请稍后重试")@ApiResponse(responseCode = "3101", description = "用户不存在")public R<SysUserVO> detail(@RequestParam(required = true) Long userId, @RequestParam(required = false) String sex) {return null;}
}