知识卡片
文档生成路径决定维护责任
书中比较“先写 OpenAPI 文档、再生成代码框架”和“先写代码注解或注释、再生成文档”。前者便于前后端测试提前约定契约,但开发中要持续保持实现与规范一致;后者降低已有代码的文档起步成本,却可能因注解或注释遗漏而让已发布行为未被描述。选择入口时应指定唯一可信的契约来源,并把生成、审查与契约测试纳入变更流程。书中 Swagger UI 随应用发布与 apiDoc 静态站点独立发布,是交付形态的差异,不直接决定内容准确性。
这张卡片看不懂?
这张卡片的反馈已满 10 条,暂时无法继续提交。
已有反馈 · 0 / 10 条
还没有人提交反馈。
原书出处
参考来源
- 位置:《架构探险:轻量级微服务架构(下册)》第25章《6.3 自动生成REST API文档》(源文件:_epub-src/OEBPS/Text/part0011_split_003.html)
- 结论依据:原文分别展示 Editor→Codegen、Controller 注解→Swagger UI、Controller 注释→apiDoc 静态站点三条路径;维护责任是对这些路径的归纳。
- 原始内容:我们先通过Swagger Editor来设计REST API文档,然后通过Swagger Codegen快速生成指定编程语言的服务端或客户端