我对Web API描述语言世界很陌生,刚刚开始为我们的JAX-RS应用程序研究Swagger,API Blueprint和RAML。 它们看起来都很棒,但我有一个问题。
我的理解是自上而下的方法,你首先设计API,生成一个很好的HTML文档,可能还有一个模拟,然后开始编码。
但是,如果您最终必须更改API的签名,例如,在实施过程中由于某些原因更改响应主体模型,该怎么办? 我的意思是,在这种情况下,您需要更改API规范,并且必须手动编辑API规范以使其与代码保持同步,因为似乎没有成熟的库从源代码生成API规范。 (我已经为Swagger和RAML测试了这样的库,但没有测试APIB,因为我找不到JAX-RS源-APIB转换库。) 在上述情况下,你如何处理它?
您是手动编辑API规范还是使用某些库自动执行此操作? 如果是后者,请告诉我图书馆的名称?
答案 0 :(得分:2)
如果您想确保您的API说明和文档同步,请务必查看Dredd。
Dredd的标语是:
不再有过时的API文档
Dredd是一个API测试框架,它使用API Blueprint并针对API后端进行测试。您可以非常轻松地将其作为测试套件的一部分,以便它可以成为整个开发生命周期的一部分。从设计到本地TDD,持续集成甚至是实时API的部署后验证。
所以我建议手动编辑/编写API描述作为设计过程的一部分,然后测试它而不是从代码生成文档。
免责声明:我是Dredd维护者
答案 1 :(得分:0)
对于RAML,您可以查看abao。它是一个命令行实用程序,用于检查RAML规范是否与后端实现匹配。我自己没有用它,但它似乎相当于Dredd。