在CloudFlare仪表板中可以执行的所有操作也可以通过restfulapi实现。我们使用相同的API来驱动仪表板本身。为了跟踪我们所有的端点，我们使用了一种称为JSON hyperschema的丰富表示法。这些模式用于生成完整的HTML文档，您可以在https://api.cloudflare.com。今天，我们想分享一组我们在这个过程中使用的工具。理查德·马丁的CC BY 2.0图像JSON架构JSON模式是描述JSON数据格式的强大方法。它提供了完整的结构验证，并可用于对传入请求的验证。JSON超模式通过链接进一步扩展了这种格式，并为您提供了一种描述API的方法。JSON模式示例{"type"："object"，"属性"：{"name"：{"type"："string"}，{"：{age"："}"类型，"地址"：{"type"："object"，"属性"：{"街道地址"：{"type"："string"}，"城市"：{"type"："string"}，"state"：{"type"："string"}，"country"：{"type"："string"}}}}}匹配JSON{"name"："约翰·多伊"，"年龄"：45岁，"地址"：{"street_address"："12433 State St NW"，"城市"："亚特兰大"，"state"："格鲁吉亚"，"country"："美国"}}JSON模式支持所有简单数据类型。它还定义了一些特殊的元属性，包括title、description、default、enum、id、$ref、$schema、allOf、anyOf、oneOf等等。最强大的构造是$ref。它提供了与超文本链接类似的功能。您可以引用外部架构（外部引用）或当前架构中的片段（内部引用）。通过这种方式，您可以轻松地将多个模式组合在一起，而无需重复自己。JSON超模式引入了另一个名为links的属性，您可以在其中定义API链接、方法、请求和响应格式等。了解JSON模式的最佳方法是访问了解JSON模式。您也可以访问官方规范网站或wiki。如果你想直接跳到例子中，试试这个。托尼·沃尔姆斯利2.0图片生成文档：工具我们已经有了一个开源库，可以从JSON模式文件和把手.js模板。它被称为JSON模式文档生成器（JSDC）。但是，它有一些缺点，使得它很难用于其他团队：复杂结构每一次改变都需要重建（缓慢）模板不能有自己的依赖项所有其他脚本必须位于不同的位置很难对其进行进一步的定制（分成部分、页面）我们需要更模块化和可扩展的东西来解决上述问题，同时仍然准备好输出，只需要几个命令。因此，我们创建了一个基于JSDC和现代JavaScript库的工具链。本文不仅描述了如何使用这些工具，还解释了我们的设计决策。它是以自下而上的方式描述的。如果您对技术讨论不感兴趣，只想开始使用工具，可以跳到底部。json架构加载器JSON架构文件需要先进行预处理。我们要做的第一件事是解决他们的引用（$ref）。这可能是一个相当复杂的任务，因为每个模式都可以有多个引用，其中一些引用是外部的（引用更多的模式）。另外，当我们进行更改时，我们只希望解析需要解析的模式。我们决定使用Webpack执行此任务，因为Webpack loader具有一些很好的属性：这是一个将输入转换为输出的简单函数它可以维护和跟踪附加的文件依赖关系它可以缓存输出它可以用链子拴住Webpack监视所需模块及其依赖项中的所有更改我们的加载器使用第三方JSON Schema Ref解析器库。它不遵循与id属性相关的JSON模式规范以及它们更改引用范围的能力，因为它是不明确的。但是，它确实实现了JSON指针和JSON引用规范。这是什么意思？您仍然可以将相对（或绝对）路径与JSON指针结合起来，并使用如下引用："$ref"：/product.json/definitions/identifier"但是id被简单地忽略了，并且作用域总是相对于根。这使得我们的模式更容易推理。也就是说，一个唯一的根id仍然用于其他目的。json模式示例加载程序最后，我们解析了模式。不幸的是，它们的结构与我们最终的HTML文档不匹配。它可以是深层嵌套的，我们希望向用户展示API请求和响应的良好示例。我们需要做进一步的转变。我们必须删除一些原始属性并预先计算新的属性。我们的目标是创建一个更适合我们的UI组件的数据结构。请查看项目页面了解更多详细信息。你可能会问我们为什么使用另一个webpack加载器，为什么这不是我们的web应用程序的一部分。主要原因是性能。我们不希望通过重复地执行这些转换来阻塞浏览器，因为JSON模式可以任意嵌套，非常复杂，并且可以预先计算输出。doca引导主题有了这两个webpack加载程序，您可以轻松地使用您最喜欢的JavaScript框架来构建自己的应用程序。然而，我们想让文档生成可以访问，即使是那些没有时间构建自己的应用程序的人。因此，我们创建了一组与json模式示例加载程序的输出相匹配的模板。这些模板使用流行的库React。为什么要反应？它可以在服务器端使用和呈现我们现在可以将其他特性烘焙到组件中（例如，显示/隐藏…）它很容易合成我们真的很喜欢它：）doca引导主题是一个基于twitterbootstrapv3的通用主题。我们也有我们的私人doca cf主题使用https://api.cloudflare.com。我们鼓励你把它分开，创造你自己的精彩主题！由Maia Coimbra提供的CC BY 2.0图像doca公司所以，我们有加载器和漂亮的UI组件。现在，是时候把它们放在一起了。我们有办法做到这一点！我们称之为doca。doca是一个用节点.js这为你提供了整个申请的框架。其实很简单。它采用经过微调的webpack/redux/babel应用程序，将其复制到您选择的目的地，并进行一些简单的替换。由于所有的努力都是由webpack加载程序完成的，而且所有UI组件都位于不同的主题包中，所以最终的应用程序可能非常小。它不打算由doca工具更新。你应该只使用doca一次。否则，它只会重写应用程序，如果您进行了一些自定义修改，这是不可取的。例如，您可能需要添加React Router来创建多页文档。doca包含用于开发和生产模式的web包配置。您可以不使用JavaScript构建一个完全静态的版本。它将json模式示例装入器的输出转换为不可变的数据结构（使用不可变.js). 这带来了一些不错的性能优化。然后将这个不可变的结构传递给doca引导主题（默认选项）。就这样。这是易于安装和未来定制之间的一个很好的折衷方案。您是否有一个包含JSON模式文件的文件夹并希望快速获取index.html？安装doca并使用一些命令。你需要自己的造型吗？派生并更新doca引导主题。您是否需要创建更多页面、节或使用其他框架？只需修改doca搭建的应用程序。webpack最酷的特性之一是热模块更换。保存文件后，可以立即在浏览器中看到结果。没有等待，刷新，滚动或丢失状态。它主要与React结合使用；但是，我们也将其用于JSON模式。下面是一个演示：它变得更好了。你的模式很容易出错。别担心！系统将立即提示您一条描述性错误消息。一旦修好了，你就可以继续你的工作了。不用离开你的编辑。昨天太爽了！生成文档：用法唯一的先决条件是节点.js系统上的v4+版本。然后，您可以安装doca：npm安装doca-g只有两个简单的命令。第一个是doca init：doca init[-i架构\文件夹][-o项目\文件夹][-t主题\名称]它遍历当前目录（或schema_文件夹），查找**/*.json文件，并生成/documentation（或/project_文件夹）。当您需要引导项目时，此命令只应使用一次。第二个主题是doca主题：doca主题新主题项目这给了这个项目一个不同的主题（newTheme）。它有两个步骤：它称为npm install newTheme——保存在项目内部它将所有doca xxx主题引用重命名为doca newTheme主题这可能会对项目产生破坏性的更改。总是使用版本控制！CC BY 2.0图片作者：Robert Couse Baker入门最好的方法是试试我们的例子。它包括两个JSON模式。git克隆git@github.com：cloudflare/文档.gitcd文档/示例doca初始化cd文档npm安装npm启动打开：8000个就这样！这就产生了一个开发环境，在这个环境中，您可以快速更改模式，并且由于强大的热重新加载，可以立即看到效果。您可以使用以下内容构建静态生产就绪应用程序：npm运行构建开放式生成/索引.html或者，您可以使用以下命令在不使用JavaScript的情况下构建它：npm运行建造：nojs开放式生成/索引.html是否需要添加更多架构或更改其顺序？编辑文件/架构.js.您想更改通用页面标题还是使curl示例更好？编辑文件/配置文件.结论我们正在开源一组库，可以帮助您开发和发布丰富的restfulapi文档。我们很高兴收到任何反馈，并迫不及待地想看到开源社区创建的新主题。拜托，在GitHub上给我们一颗星星。另外，如果你对这项工作感兴趣，那么你应该加入我们的团队！