课件Spring Boot+Vue全栈应用开发实践 课件17 使用 SpringDc 生成接口文档

罗荣良使用SpringDoc生成接口文档本节学习目标1.理解API文档在前后端分离开发中的重要性2.认识OpenAPI规范与SpringDoc框架3.实战：集成SpringDoc并访问SwaggerUI4.掌握常用注解优化文档显示(@Tag,@Operation)5.学会通过文档在线调试接口痛点：前后端的“扯皮”日常场景对话：前端：“这个接口传什么参数？”后端：“去看代码啊！”前端：“返回的JSON结构变了？”后端：“哦，忘改文档了...”结论：手动维护文档是灾难。解决方案：自动化文档核心理念：代码即文档(CodeasDocumentation)。机制：框架自动扫描Controller代码和注解，生成标准文档。优势：实时同步、在线调试、减少沟通成本。OpenAPI：一套描述RESTAPI的国际标准规范(类似HTML标准)Swagger：实现该规范的一套工具集(UI,Editor)SpringDoc：SpringBoot的库，自动生成OpenAPI规范文档概念辨析：OpenAPIvsSwaggervsSpringDoc为什么选择SpringDoc？历史背景：Springfox(停止维护)vsSpringDoc(活跃)。SpringDoc优势：1.支持OpenAPI3.0+。2.完美支持SpringBoot3。3.配置简单，社区活跃。实战第一步：引入依赖实战第二步：启动与访问启动SpringBoot应用。访问地址：http://localhost:8080/swagger-ui/index.html核心JSON地址：/v3/api-docs初识SwaggerUI界面SwaggerUI默认界面。展示：自动扫描到的student-controller以及GET/POST等接口。问题：默认名字

不够直观，参数说明缺失。优化文档1：控制器描述(@Tag)Before:StudentControllerAfter:@Tag(name="学生管理",description="学生增删改查API")效果：文档分组名称变中文，清晰明了。

代码演示：@Operation(summary="根据ID查询",description="返回详细信息")位置：放在Controller的方法上。效果：接口列表不再是冷冰冰的URL。优化文档2：接口描述(@Operation)优化文档3：实体描述(@Schema))代码演示(Student类)：@Schema(description="学生姓名",example="张三")privateStringname;效果：Schema部分显示字段含义和示例值。配置SpringDoc配置文件perties：springdoc.api-docs.enabled=truespringdoc.swagger-ui.path=/doc.html(自定义访问路径)springdoc.swagger-ui.tryItOutEnabled=true(开启调试)操作流程：1.点击接口->Tryitout2.填写参数(ExampleValue自动填充)3.Execute->查看ResponseBody和Code。实战演示：在线调试(Tryitout)前后端协作新模式后端编写代码->自动更新文档->前端查看Swagger->在线mock数据/调试->正式联调。价值：协作劳动--契约精神，高效协作。本节小结与作业小结：SpringDoc集成、常用注解、Swagge