示例代码片段生成器¶
Launchpad蓝图
https://blueprints.launchpad.net/trove/+spec/example-snippet-generator
问题描述¶
Trove 拥有一些非常好的文档，其中包含代码片段，展示了标准 REST 调用和响应的 JSON 格式。唯一的问题是这些文档没有经过验证，这意味着如果 API 发生变化，无论大小，它们可能与当前 Trove 用户看到的内容不匹配。
提议的变更¶
此蓝图建议我们通过自动生成这些示例并在 Trove 中对其进行验证来解决此问题。
该修复将涉及实际对真实的 Trove 代码进行调用，并捕获请求和响应的主体，然后将它们写入文档使用的文本文件。我们可以通过利用 Tox 已经运行的测试中使用的相同的“假模式”测试双关来快速完成此操作。其优点在于，所有确定请求和响应外观的 API 代码都将像执行针对完全启动的 Trove 环境的测试一样运行，并且可以更改某些 UUID 以避免它们在每次测试运行时发生变化。
配置¶
无
数据库¶
无
公共 API¶
无
公共 API 安全¶
无
内部 API¶
无
Guest Agent¶
无
数据模型影响¶
无。
REST API 影响¶
没有，除了它将比以前得到更好的测试。
安全影响¶
无。
通知影响¶
无。
其他最终用户影响¶
无。
性能影响¶
代码片段生成将在 Tox 的几秒钟内运行。对 Trove 的开发人员不会有明显的影响。
其他部署者影响¶
无。
开发者影响¶
生成速度足够快，对大多数开发人员来说几乎是不可见的。但是，开发人员会意识到他们是否无意中更改了请求或响应负载中的任何内容，并且必须为 API 的更改辩护，即使只是添加。
社区影响¶
代码片段的生成将迎来开发者和文档编写者合作的新黄金时代。也许有时开发者会成为文档编写者，或者文档编写者会成为开发者。 认为这将是一个乌托邦并不为过。
备选方案¶
我们可以继续暗示开发者总是不断阅读文档并将此视为合同，并且每次更改时他们都会疯狂地运行集成测试，但也手动运行测试并检查输出，确保文档中显示的代码片段是准确的。不幸的是，由于当前许多代码片段不准确，我认为这行不通。
依赖项¶
无。
