企业官网建设流程全解析

【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

结论：Spring Boot 4 必须用 SpringDoc，SpringFox 已被淘汰。

下面是 SpringDoc 与 SpringFox 的选型决策流程：

二、集成 SpringDoc

2.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/json

2.3 访问 Swagger UI

启动项目后，浏览器访问：

http://localhost:8080/swagger-ui.html

你就能看到自动生成的 API 文档页面，包含所有 Controller 的接口信息，并且可以直接在页面上测试。

下面是用户通过 Swagger UI 调用 API 的完整时序：

三、注解增强文档

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.Configuration@ConfigurationclassOpenApiConfig{@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 注解

@RestController@RequestMapping("/api/products")@Tag(name="商品管理",description="商品的增删改查接口")// ← 分组标签classProductController(privatevalproductService:ProductService){@Operation(summary="查询单个商品",// ← 接口摘要description="根据商品 ID 查询商品详细信息"// ← 详细描述)@ApiResponses(ApiResponse(responseCode="200",description="查询成功"),ApiResponse(responseCode="404",description="商品不存在"))@GetMapping("/{id}")fungetById(@Parameter(description="商品 ID",required=true)// ← 参数说明@PathVariableid:Long):ApiResponse<ProductResponse>{returnApiResponse.success(productService.findById(id))}@Operation(summary="创建商品")@PostMapping@ResponseStatus(HttpStatus.CREATED)funcreate(@RequestBody@Validrequest:CreateProductRequest):ApiResponse<ProductResponse>{returnApiResponse.success(productService.create(request))}}

3.3 DTO 注解

@Schema(description="创建商品请求")dataclassCreateProductRequest(@Schema(description="商品名称",example="机械键盘",required=true)@field:NotBlank(message="商品名称不能为空")valname:String,@Schema(description="商品价格",example="299.00",required=true)@field:DecimalMin(value="0.01",message="价格必须大于 0")valprice:BigDecimal,@Schema(description="库存数量",example="50",required=true)@field:Min(0)valstock:Int,@Schema(description="商品分类",example="外设",required=true)@field:NotBlankvalcategory:String)@Schema(description="商品响应")dataclassProductResponse(@Schema(description="商品 ID",example="1")valid:Long,@Schema(description="商品名称",example="机械键盘")valname:String,@Schema(description="商品价格",example="299.00")valprice:BigDecimal,@Schema(description="库存数量",example="50")valstock:Int,@Schema(description="是否有库存",example="true")valinStock:Boolean)

下面是 Controller、Service、DTO 之间的协作关系：

四、生产环境关闭文档

API 文档不应在生产环境暴露。用 Spring Profile 控制：

# application-prod.ymlspringdoc:api-docs:enabled:false# 关闭 API 文档swagger-ui:enabled:false# 关闭 Swagger UI

或者用@Profile注解：

@Bean@Profile("!prod")// 非 prod 环境才生效funcustomOpenAPI():OpenAPI{...}

五、本篇小结

模块四总结

恭喜完成 Web 深入模块！

mini-shop 现在具备了生产级 Web 应用的全部要素：

✅ 统一异常处理 + 统一响应格式 ✅ 完善的 DTO 设计 ✅ 请求日志 + 耗时统计 ✅ CORS 跨域支持 ✅ 文件上传（商品图片） ✅ API 文档（Swagger UI）

下篇预告

第 30 篇：Spring Security 7 核心概念

认证和授权有什么区别？FilterChain 怎么工作？下一篇进入安全认证模块，为 mini-shop 添加用户登录和权限控制。

如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。