—知识点专栏—Swagger/SpringDoc 从入门到上手使用前言在前后端分离的项目开发中一份清晰、实时更新的接口文档至关重要。它不仅能减少沟通成本还能提高开发与联调效率。Swagger正是为此而生。它能根据代码自动生成接口文档并内置测试功能。本文以一个“在线OJ系统”为例带你从零掌握 SwaggerSpringDoc的核心用法。一、为什么需要统一的接口文档在没有规范文档时我们常遇到这些痛点格式不一致不同接口返回的数据结构各异前端要写多套解析逻辑。错误难定位缺乏统一的状态码报错信息千奇百怪。维护噩梦人员变动后新成员需要翻代码才能知道接口定义。因此我们先定义了统一的响应格式和状态码体系。1. 统一响应体RT所有接口都套用此结构包含状态码、消息和数据。publicclassRT{privateintcode;// 状态码privateStringmsg;// 提示消息privateTdata;// 数据体}2. 自定义业务状态码我们使用枚举ResultCode来管理状态比单纯用HTTP状态码更安全、语义更明确。GetterAllArgsConstructorpublicenumResultCode{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,您已被列入黑名单请联系管理员.),// ... 其他状态码}有了这些基础后Swagger就能把这些状态码和响应结构清晰地展示给前端。二、什么是 Swagger / SpringDocSwagger 是一套开源的API文档工具。在Spring Boot项目中我们通常使用SpringDoc这个库它实现了Swagger的规范能自动扫描接口并生成可交互的在线文档。三、项目实战引入 SpringDoc1. 创建公共模块并引入依赖我们在项目中创建一个公共模块oj-common-swagger在它的pom.xml中加入dependencygroupIdorg.springdoc/groupIdartifactIdspringdoc-openapi-starter-webmvc-ui/artifactIdversion2.2.0/version/dependency2. 编写 Swagger 配置类新建SwaggerConfig.java用来设置文档的标题、描述和版本importio.swagger.v3.oas.models.OpenAPI;importio.swagger.v3.oas.models.info.Info;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;ConfigurationpublicclassSwaggerConfig{BeanpublicOpenAPIopenAPI(){returnnewOpenAPI().info(newInfo().title(在线OJ系统).description(在线OJ系统接口文档).version(v1));}}3. 让Spring Boot自动装配为了让其他服务引入该模块时配置能自动生效在resources目录下创建文件META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件内容为你的配置类全路径com.site.common.swagger.config.SwaggerConfig4. 在业务服务中使用比如在oj-sys-server服务中引入公共模块即可dependencygroupIdcom.bite/groupIdartifactIdoj-common-swagger/artifactIdversion${oj.common.swagger.version}/version/dependency启动项目后访问http://localhost:你的端口/swagger-ui/index.html就能看到文档页面了。四、使用注解细化接口文档光有“骨架”还不够我们需要用注解来详细描述每个接口。1.Tag给Controller打标签用在类上对接口进行分组。RestControllerRequestMapping(/sysUser)Tag(name管理员用户API)publicclassSysUserController{// ...}2.Operation和ApiResponse描述接口与响应用在方法上说明接口的作用及可能返回的状态码。Operation(summary新增管理员,description根据提供的信息新增管理员用户)PostMapping(/add)ApiResponse(responseCode1000,description操作成功)ApiResponse(responseCode2000,description服务繁忙请稍后重试)ApiResponse(responseCode3101,description用户已存在)publicRVoIdadd(RequestBodySysUserSaveDTOsaveDTO){returnnull;}3.Parameter描述输入参数用于明确参数的名称、位置路径、查询等和描述。路径参数示例DeleteMapping(/{userId})Operation(summary删除用户,description通过用户id删除用户)Parameters(value{Parameter(nameuserId,inParameterIn.PATH,description用户ID)})ApiResponse(responseCode1000,description成功删除用户)ApiResponse(responseCode2000,description服务繁忙请稍后重试)ApiResponse(responseCode3101,description用户不存在)publicRVoIddelete(PathVariableLonguserId){returnnull;}查询参数示例Operation(summary用户详情,description根据查询条件查询用户详情)GetMapping(/detail)Parameters(value{Parameter(nameuserId,inParameterIn.QUERY,description用户ID),Parameter(namesex,inParameterIn.QUERY,description用户性别)})ApiResponse(responseCode1000,description成功获取用户信息)ApiResponse(responseCode2000,description服务繁忙请稍后重试)ApiResponse(responseCode3101,description用户不存在)publicRSysUserVOdetail(LonguserId,RequestParam(requiredfalse)Stringsex){returnnull;}五、在线测试Swagger 的“隐藏大招”Swagger UI 不只用来“看”更强大的是直接在网页上测试接口。打开页面后找到你要测试的接口比如“新增管理员”。点击Try it out按钮。按照文档提示在 Request body 中填入正确的JSON参数。点击Execute发送请求。页面上会立刻展示出真实的响应体、响应状态码等信息完全不需要打开Postman。这在开发阶段能极大地提升效率。总结用好 Swagger / SpringDoc核心在于做好两点先定义好统一的响应格式和状态码让文档有规可循。熟练使用Tag、Operation、ApiResponse、Parameter等注解把接口信息详尽、准确地描述出来。Swagger 官方https://swagger.io/SpringDoc 官方https://springdoc.org/#swagger-ui-support