知识卡片
注解生成文档仍须核对契约
书中在 Spring MVC Controller 方法上加接口摘要、参数和响应等注解,经 Springfox 扫描后生成 Swagger UI 与 JSON 定义。它减少手写重复文档,但文档只反映扫描到的声明,不能证明 Controller 已实现或行为正确;书中明确先给未实现的方法加注解,待与前端确认后才填业务逻辑。发布前仍需用测试核对实际请求、状态码和响应与契约一致。具体依赖、注解和 /v2/api-docs 路径均是书中版本的示例。
这张卡片看不懂?
这张卡片的反馈已满 10 条,暂时无法继续提交。
已有反馈 · 0 / 10 条
还没有人提交反馈。
原书出处
参考来源
- 位置:《架构探险:轻量级微服务架构(下册)》第25章《6.3 自动生成REST API文档》(源文件:_epub-src/OEBPS/Text/part0011_split_003.html)
- 结论依据:原文说明注解扫描生成文档,且此时 Controller 方法尚未完成,后续再填实现与测试。
- 原始内容:我们当前的目标只是通过Swagger注解来生成REST API文档,因此现在我们无须完成Controller方法。