协议或接口描述工具

Question

我们必须开发一个协议作为不同公司的不同系统之间的接口描述。这些实现将由每个公司的开发人员以不同的语言（未知）进行。

但是，我们希望在文本描述基础上一起开发协议。我将获得当前版本的基本副本，并希望将其发送给所有人以供评论。

这样做的好工具是什么？

目前我们正在使用MS Word导致几个问题：

• 我们需要大量时间进行文本格式化。
• 无法在方法说明中引用数据类型。
• 措辞不同章节（不同作者）并且很难对齐。

完美将是：

• 带有词汇表和自动完成功能的工具。
• 使用活动链接引用其他项目（方法，数据类型......）。
• 自动生成人类可读（PDF-）文档。

你知道这样的工具吗？

PS：我没有让Sparx Systems Enterprise Architect完成这项工作。也许还有这个提示？

Answer 1

这是一个非常大的问题，因为您可能（应该）希望在协议规范中记录许多可能的方面。最重要的两个是数据结构和消息序列，然后是错误管理，身份验证，定时等等。

UML当然可以用来描述这些东西，而Enterprise Architect非常能够从模型中生成多种文档 - 它肯定会对您的参考问题有所帮助。但首先，您必须非常严格地确定如何对协议的每个方面进行建模，并且您需要构建必要的EA配置/适配。

为了从EA中获取高质量的文档，我建议使用对象模型的DocumentGenerator类从加载项生成文档，因为这比传统的RTF生成器更灵活 - 一方面，您可以访问Word的除EA之外的API，因此对文档的处理远远超过仅使用EA的API。

在不知道协议的大小或复杂程度的情况下，我会说至少需要几周时间才能为那些在编写EA改编方面经验丰富的人工作。但是，如果您的项目范围涉及多家公司，则可能值得投资。