第29篇-SpringDoc-OpenAPI3-API文档

【Kotlin Spring Boot 4 从零到架构师】第 29 篇SpringDoc OpenAPI 3 — API 文档本系列定位零基础入门从 Kotlin 语法一路到 Spring Boot 4 高级架构DDD Modulith适合 Java 开发者转型也适合纯新手系统学习。本篇你将学到SpringDoc OpenAPI 3 的集成与配置Tag/Operation/Schema/Parameter注解在 Swagger UI 中测试 API按模块分组 API 文档生产环境关闭文档学完本篇mini-shop 将拥有一份专业、可交互的 API 文档前后端联调效率倍增。一、SpringDoc vs SpringFox维度SpringFoxSwagger 2SpringDocOpenAPI 3规范Swagger 2.0OpenAPI 3.1Spring Boot 4 支持❌ 已停止维护✅ 官方推荐启动速度慢扫描全部类快配置复杂度高低结论Spring Boot 4 必须用 SpringDocSpringFox 已被淘汰。下面是 SpringDoc 与 SpringFox 的选型决策流程Spring Boot 3.x / 4.xSpring Boot 2.x是否项目启动Spring Boot 版本推荐 SpringDoc是否愿意升级继续使用 SpringFox不推荐添加 springdoc-openapi 依赖配置 application.yml享受 OpenAPI 3 的自动文档二、集成 SpringDoc2.1 添加依赖dependencies{implementation(org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0)}2.2 配置# application.ymlspringdoc:api-docs:path:/v3/api-docs# API 文档 JSON 路径swagger-ui:path:/swagger-ui.html# Swagger UI 页面路径operationsSorter:method# 接口按 HTTP 方法排序tagsSorter:alpha# 标签按字母排序packages-to-scan:com.example.minishop# 扫描包default-produces-media-type:application/json2.3 访问 Swagger UI启动项目后浏览器访问http://localhost:8080/swagger-ui.html你就能看到自动生成的 API 文档页面包含所有 Controller 的接口信息并且可以直接在页面上测试。下面是用户通过 Swagger UI 调用 API 的完整时序数据库Spring Boot 应用Swagger UI开发者/前端数据库Spring Boot 应用Swagger UI开发者/前端1. 访问 /swagger-ui.html2. 请求 /v3/api-docs3. 返回 OpenAPI JSON4. 渲染 API 文档页面5. 填写参数并点击 Try it out6. 发送 HTTP 请求7. 执行数据库操作8. 返回数据9. 返回响应 JSON10. 展示响应结果三、注解增强文档3.1 全局信息配置packagecom.example.minishop.configimportio.swagger.v3.oas.models.OpenAPIimportio.swagger.v3.oas.models.info.Contactimportio.swagger.v3.oas.models.info.Infoimportio.swagger.v3.oas.models.info.Licenseimportorg.springframework.context.annotation.Beanimportorg.springframework.context.annotation.ConfigurationConfigurationclassOpenApiConfig{BeanfuncustomOpenAPI():OpenAPI{returnOpenAPI().info(Info().title(Mini-Shop API 文档).version(1.0.0).description(极简电商系统 RESTful API 接口文档).contact(Contact().name(Mini-Shop Team)))}}3.2 Controller 注解RestControllerRequestMapping(/api/products)Tag(name商品管理,description商品的增删改查接口)// ← 分组标签classProductController(privatevalproductService:ProductService){Operation(summary查询单个商品,// ← 接口摘要description根据商品 ID 查询商品详细信息// ← 详细描述)ApiResponses(ApiResponse(responseCode200,description查询成功),ApiResponse(responseCode404,description商品不存在))GetMapping(/{id})fungetById(Parameter(description商品 ID,requiredtrue)// ← 参数说明PathVariableid:Long):ApiResponseProductResponse{returnApiResponse.success(productService.findById(id))}Operation(summary创建商品)PostMappingResponseStatus(HttpStatus.CREATED)funcreate(RequestBodyValidrequest:CreateProductRequest):ApiResponseProductResponse{returnApiResponse.success(productService.create(request))}}3.3 DTO 注解Schema(description创建商品请求)dataclassCreateProductRequest(Schema(description商品名称,example机械键盘,requiredtrue)field:NotBlank(message商品名称不能为空)valname:String,Schema(description商品价格,example299.00,requiredtrue)field:DecimalMin(value0.01,message价格必须大于 0)valprice:BigDecimal,Schema(description库存数量,example50,requiredtrue)field:Min(0)valstock:Int,Schema(description商品分类,example外设,requiredtrue)field:NotBlankvalcategory:String)Schema(description商品响应)dataclassProductResponse(Schema(description商品 ID,example1)valid:Long,Schema(description商品名称,example机械键盘)valname:String,Schema(description商品价格,example299.00)valprice:BigDecimal,Schema(description库存数量,example50)valstock:Int,Schema(description是否有库存,exampletrue)valinStock:Boolean)下面是 Controller、Service、DTO 之间的协作关系调用返回接收返回使用ProductControllergetById(id: Long) : ApiResponsecreate(request: CreateProductRequest) : ApiResponseProductServicefindById(id: Long) : ProductResponsecreate(request: CreateProductRequest) : ProductResponseCreateProductRequestString nameBigDecimal priceint stockString categoryProductResponseLong idString nameBigDecimal priceint stockboolean inStockApiResponseTint codeString messageT data四、生产环境关闭文档API 文档不应在生产环境暴露。用 Spring Profile 控制# application-prod.ymlspringdoc:api-docs:enabled:false# 关闭 API 文档swagger-ui:enabled:false# 关闭 Swagger UI或者用Profile注解BeanProfile(!prod)// 非 prod 环境才生效funcustomOpenAPI():OpenAPI{...}五、本篇小结知识点核心内容SpringDocOpenAPI 3 实现Spring Boot 4 推荐springdoc-openapi-starter-webmvc-ui一行依赖集成 Swagger UITagController 分组标签Operation接口摘要和描述SchemaDTO 字段说明和示例值Parameter路径/查询参数说明ApiResponses响应状态码说明生产关闭springdoc.api-docs.enabled: false模块四总结恭喜完成 Web 深入模块篇主题核心收获24全局异常处理RestControllerAdvice、统一 ErrorResponse25统一响应格式ApiResponseTPageResponseT26DTO 设计模式请求/响应分离、扩展函数映射、copy() 部分更新27拦截器与过滤器日志统计、权限校验、请求 ID28CORS 与文件上传全局跨域配置、MultipartFile 上传29SpringDoc OpenAPI可交互 API 文档mini-shop 现在具备了生产级 Web 应用的全部要素✅ 统一异常处理 统一响应格式 ✅ 完善的 DTO 设计 ✅ 请求日志 耗时统计 ✅ CORS 跨域支持 ✅ 文件上传商品图片 ✅ API 文档Swagger UI下篇预告第 30 篇Spring Security 7 核心概念认证和授权有什么区别FilterChain 怎么工作下一篇进入安全认证模块为 mini-shop 添加用户登录和权限控制。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。