Perl：记录和验证 API 输入/输出的模式语言？答案

【问题标题】：Perl: schema language to document and validate API input / output?Perl：记录和验证 API 输入/输出的模式语言？
【发布时间】：2014-07-16 01:19:02
【问题描述】：

我们正在创建一个 perl 和 HTTP 支持的 RPC 样式 API。我们正在寻找一个库来记录 API 输入/输出并特别是验证 API 输入。我们最初只支持 XML，但现在主要转向 JSON 输入/输出。但目前：XML 和 JSON。

对于 XML，我们使用嵌入 POD 中的RELAX NG 来记录输入和输出的外观，并验证输入和可选输出，而不是仅仅为人类记录输入和输出结构。但这不适用于 JSON，因此目前我们不能/不验证 JSON。

我们考虑过JSON::Schema，因为它可以验证perl 数据结构，因此可以同时用于XML 和JSON。但是依赖关系超出了我们在 debian stable 上的承受能力。所以 JSON::Schema 对我们来说是不可能的。

还有哪些其他选择？

编辑添加：理想情况下，我们希望对输入/输出数据的验证与Liquid Web's documentation 中一样详细。一个好处是自动生成文档（如 Liquid Web）和测试用例生成。

【问题讨论】：

这可能得到关于softwarerecs的回应，我认为那里的主题更多。查看对deps.cpantesters.org/?module=JSON%3A%3ASchema;perl=latest 的依赖关系，如果我正在编写Web 服务，我看不到任何让我担心的事情。你能更具体地谈谈他们的问题吗？
JSON::Schema 需要更新版本的 Test::More、JSON、ExtUtils::MakeMaker 和其他完全缺失的模块。前段时间我至少花了一天时间，经过多次尝试，每次都花费一个多小时的 CPAN 安装依赖项，修复包 foo、bar 和 baz 中未声明的依赖项，我终于放弃了。今天，我只是让 Makefile.PL 做它的 CPAN 事情 - 四个错误，这里 2：[ERROR] No such module 'Config' found on CPAN 和 Can't locate object method "init_tools" via package "PACK001" at /usr/local/share/perl/5.10.1/ExtUtils/MakeMaker.pm line 661. 这里很多小时..
我会考虑 Data::Sah，我用它来记录 Web API 以及函数和 CLI，但它目前也有很多依赖项。

【解决方案1】：

考虑使用哈希来定义和强制执行代码中可接受的输入/输出，然后从源代码本身生成文档。这样您就不必维护您的 api 接口的单独文档，并且您将更有可能注意到您的 api 中的问题。我以前做过这个并取得了很大的成功:)

【讨论】：

OK ... 完成此操作的代码非常复杂，API 也是如此。
酷！对不起，我不是故意贬义的。但是解析 perl 代码很脆弱，我希望有一种方法可以做到这一点，而不必自己发明轮子。
不用担心。这是大量的工作——它工作的部分原因是我们有一个非常一致的结构化 api 和一组关于如何定义允许的输入/输出的规则。一个好处是，我们有时会在设置输入/输出要求的方式中发现错误，因为生成的文档表明存在明显错误，并且一致性检查错误失败或查看文档的人可能会发现错误。当文档帮助编写代码时，总感觉像是一场胜利，反之亦然:) 抱歉，我不知道有什么模块可以让这变得更容易。