Api-blueprint: 模块化

对于那些有大量 API 的情况，可能在公司的不同组的控制下，这绝对是天赐之物。

@rurounijones只是为了澄清这个功能意味着“能够将一个 API 描述拆分为多个文件”。

有人对此有任何想法吗？ 根据我之前对Drafter的评论https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

选项是在蓝图顶部添加一些包含/需要工具，或者只是从一个目录中获取所有蓝图并将它们连接在一起。

想法？

连接更简单，但我觉得 require 会更容易使用，因为您可能需要，然后添加其他内容。

这是否只是盲目地内联文件的内容，就好像它是在专利中定义的一样，还是对文件的内容有某种限制（例如，它们可以有自己的 yaml 标头吗？与父 yaml 冲突？）我觉得没有限制会更好，但我想我会提出来。

@zdne

首先，我已经有了一个基本的系统，可以使用简单的文件连接来使用 Grunt 来管理它。 我们的蓝图变得难以管理，这是一种将其拆分为文件的快速而肮脏的方式（注意，任意多个文件，因为它们是按文件系统顺序连接的）。 我在这里发布了带有简短说明的 Gruntfile。

鉴于串联很容易自己滚动，对我来说，“官方”工具应该更强大是有道理的。 我一直在思考这个问题，试图对其他系统如何处理这个问题进行一些研究。

1. 包括/要求
   
   
   
   • 包含将在文件顶部完成，并且文件的某些部分将在其中被引用。 我认为这需要一个比当前[Model Reference][]语法更强大的引用系统。 理想情况下，包含文件中的任何节点都是可寻址的——因此可能会有[github.Users.'Create A User'][]或[github][POST /users]之类的东西。 （可能还需要像=这样的前缀）。 除了名称或 url + 方法之外，是否有更好的方法来引用 AST 中的特定节点？
   
   
   • 鉴于您有一种取消引用节点内容的好方法，这可以使用C 预处理器来完成，它会附带许多额外的功能而无需额外费用。
   
   
2. 模板系统/嵌入
   
   
   
   • 非降价 - 模板将使用单独的模板语言编写，因此雪崩无法解析模板文件。 类似的例子是grunt-readme ，看起来它可以开箱即用地模板化蓝图文件。
   
   
   • Markdown - 这类似于我们在起草者问题上讨论的=[]()或:[]()语法。 它仍然是有效的降价并且可以被雪崩解析。
   
   
3. 两个都
   
   
   
   • 鉴于您定义了引用节点的语法（ [github]['Create A User'] ）和直接嵌入（ :[/github.md](/github.md) ），看起来您可以轻松地同时拥有两者。 也许它们可以具有与:[]()相同的一般语法，并且解析器确定它是节点还是文件引用。
   
   

对此有什么想法吗？ 我错过了一些选项/工具吗？ 我有点倾向于“两者”选项，它具有用于嵌入和节点取消引用的通用语法，但也许这有点多。

鉴于串联很容易自己滚动，对我来说，“官方”工具应该更强大是有道理的

好吧，最终也许是的，但我不想过度设计它并在乞求中推出一些精简和简单的东西。

从目前存在的问题来看需要解决的问题，主要是：

1. 引用（外部）资产 - #20 并在https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071 中讨论
2. 将蓝图拆分为更易于管理的逻辑部分

出于拆分的目的，我将只考虑资源组或资源（例如，不是操作、事务示例或请求）。 至少在开始时。

广告 1：我觉得 _referenced assets_ 会被 #20 中的提案优雅地解决并讨论https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071

广告 2：我一点也不会把它复杂化。 我唯一会用于嵌入的是常规降价语法，例如[Some Text](path/to/blueprint/file.apib)或[Some Text](path/to/blueprint/file.apib#resource-name) 。 对于包含，我将遵循与起草者中的资产相同的原则，例如在参考之前使用: 。 类似于https://gist.github.com/zdne/8804418#aliens -question-aliens_question

我认为这足以开始？

我认为这足以开始？

同意。 我现在才意识到您正在区分包括“资产”和包括“资源”/“资源组”。 我一直认为它们都是可以随意包含的“节点”。

对于第二点，我认为引用现有的 MultiMarkdown 语法进行嵌入会很有用：

This is some text.

{{some_other_file.txt}}

Another paragraph

这似乎是一种包含资源的简单方法？ （或者实际上，任意文本/节点？）

所以澄清一下我的观点：

1. 我认为引用资产的一个好的语法是:[]()或=[]()所讨论的
2. 我认为一个好的嵌入语法是 multimarkdown 使用的{{ }} 。

并且还要澄清一些词汇：我_认为_当您说“包含”时，您指的是我说“包含”时的意思，即用另一个文件中的文本完全替换占位符。

如果我理解正确，“引用”和“包含”/“包含”之间的区别仅仅是为了_rendering_，比如html或pdf。 对于解析器来说，资产（例如）是否被引用或嵌入并不重要，相同的 AST 结果。 那是对的吗？

1. 我认为引用资产的一个好的语法是 :或 =如所讨论的
2. 我认为一个好的嵌入语法是多降价使用的 {{ }} 。

为什么要同时拥有这两种方法而不是一种方法？ 从语法上区分这两者有什么好处吗？ 就我个人而言，我更喜欢第一，因为它仍然呈现为您可以在普通 Markdown 中遵循的？

我认为当您说“包含”时，您指的是我说“包含”时的意思，即用另一个文件中的文本完全替换占位符。

同意，从现在开始将尝试使用嵌入。 谢谢！

如果我理解正确，“引用”和“包含”/“包含”之间的区别只是为了呈现

并不真地。 在我看来，引用（创建引用）实际上应该只添加到输出（AST）的链接，并将其余部分留在工具上（https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 )

Translcusion 应该指示解析器（或预处理器）将内容拉入......

这里只是一个更新：这确实是计划好的并且非常需要。 我们正在开发使这成为可能的工具。 同时，如果您不依赖 Apiary 在线编辑器，您可以使用类似https://gist.github.com/danvine/11087404或其他类似方法（我知道至少有少数基于 gulp 的工具）。

Whiskey 现在支持.apib扩展名，并通过其大纲视图更轻松地编辑大型 Markdown 文件：http: //vimeo.com/album/3108294/video/110486733

http://9muses.se/erato/和http://25.io/mou/也支持 .apib 如果你想要一个桌面应用程序（适用于 Mac）

罗伯特·克鲁克斯学习服务总监
布莱特科夫公司

2015 年 12 月 29 日下午 4:08，Kevin Ingersoll [email protected]写道：

Whiskey 现在支持 .apib
扩展名，并通过其大纲视图更轻松地编辑大型 Markdown 文件：http: //vimeo.com/album/3108294/video/110486733

—
直接回复此邮件或在 GitHub 上查看
.

嘿@bcls和@holic ，感谢您指出这些编辑！

相关： https ://github.com/apiaryio/api-blueprint/issues/20#issuecomment -77108398

核心开发人员对此是否做出任何决定？ 自2013年以来一直很出色，到目前为止还没有给出明确的答案，请问我们可以划清界限吗？

嘿@foxx 对此还没有任何明确的决定——我倾向于Hercule中引入的嵌入语法：

FORMAT: 1A

# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).

# Group Gist

:[Gist](blueprint/gist.md)

:[Gists](blueprint/gists.md)

除了

`````` 降价

• 模型

+ Body

  ```
  :[](gist.json)
  ```

``````

因为代码块应该对解析器/预处理器保持不透明。

此外，我不认为嵌入应该在任何级别上起作用——被嵌入的文件本身应该是有效的蓝图。

至于对此的承诺——它在功能路线图上相当高——但目前还没有预计到达时间。

我将不胜感激对此以及功能路线图可见性的任何评论或想法。

谢谢！

到目前为止，嵌入语法似乎是最好的建议，它是一种优雅而干净的方法，并且比我迄今为止看到的任何其他建议都要好。 Fwiw，来自我的 +1。

有这方面的消息吗？

嵌入方法对我来说似乎很好，我认为它没有任何缺点。

暂时我建议使用 Hercule 和:[Gist](blueprint/gist.md)语法。 将努力将其反向移植回 API 蓝图规范和解析器工具链

有没有针对这个问题做些什么？ 我还想将一个较大的 apib 文件拆分为多个。
谢谢！

嘿@adams-sarah 不幸的是不是我这边。 我仍然支持使用 Hercule (https://github.com/jamesramsay/hercule)，因为它运行良好 - 唯一的缺点是您无法在 Apiary.io 上编辑多个文件。 如果我能以某种方式提供帮助，请告诉我！

+1 使用大力神https://github.com/jamesramsay/hercule
我们已经使用它一段时间了，希望它仍然能进入 apib 规范

:+1: 用于添加此功能。

我还支持单一的 TOC/索引方法。 嵌入有点过于灵活，在我过去的经验中并没有扩展到基于 wiki 的大型文档中。

我们肯定必须将其烘焙到解析器本身以支持源映射。

同时，我们准备了一个真实的例子来展示如何使用 Hercule – https://github.com/apiaryio/api.apiblueprint.org

@zdne在我们使用 json-schema（通过 interagent/prmd）时，我们将它沿资源线拆分，并基本上强制执行特定的目录结构以暗示包含（或多或少它构建了一个顶级模式，其中包含目录中的所有内容）子模式，所以它改变了事物的层次）。 这显然非常专业于我们正在做的事情，并不特别适合您的情况，但想分享我们的经验。 与此相比，我认为嵌入似乎更加优雅/灵活，但如果有一些直接的方法来整合 TOC/索引，那肯定会很好。 也许这与我们所做的类似，即您创建一个超级蓝图作为该索引，然后嵌入/引用其中的子蓝图。 我可以看到这种自动发生的事情很好，但如果它没有碰巧做你想做的事，也会很尴尬。 无论如何，如果有帮助的话，我很乐意进一步讨论/分享我的经验。

此功能的状态如何？
我们在 Apiary.io 中使用 Pro 计划，我们需要这个功能

@DavidBM我有同样的问题。 我解决这个问题的方法是拥有两个apiary.apib文件。

未编译

apiary-source.apib - 使用包含功能的未编译源

FORMAT: 1A
HOST: https://api.example.com

# Hello World

<!-- include(blueprint/posts.apib) -->

编译

您可以简单地运行：

aglio --input apiary-source.apib --compile --output apiary.apib

您的apiary.apib现在应该包含blueprint/posts.apib的内容。

你好谢谢！ 是的，但是您不能在 apiary.io 中编辑文档

我们已经有了 Hercule 的定制解决方案，但是为我们支付 apiary pro 的目的是让产品经理在不输入 git 的情况下更新文档。 恐怕这对我们来说是一个完全的障碍，如果不解决，我们将取消与 Apiary 的合同。

在拥有 Hercule 和其他工具这么长时间后，我不希望它处于这种状态。

这是非常非常令人失望的:(

大家好，很抱歉来晚了，重新打开和挖掘旧东西。 如果这不是正确的地方，请原谅我。 但是，为了开发蓝图模拟进行研究，我发现了这个讨论，这是迄今为止我能找到的最接近的讨论。

我正在努力按模型拆分我的回复:(。是否可以将模型引用到不同的文件夹中？
我想在我的蓝图文件夹中包含我的所有请求，例如，在一个单独的模型文件夹中，我的所有实体模型（MSON/MD/JSON/whatever 文件，适合的文件）以便轻松地将它们重用到不同的响应中。 有人成功做到这一点吗？

如果这个问题得到一些关注，那就太好了。 我们的 API 蓝图中有 26000 行，这使得管理起来非常困难

我们正在使用 Dredd 实施合同测试，我们正在使用 Aglio，但如果添加它会很棒，这样我们就不必

原因之一是我们在设计上进行了很多迭代 :) 当这个问题被打开时，没有 MSON，我们仍然在嵌入与引用之间纠结。

但是为了记录，您在那里有什么需求？ 它只是多文件管理和编译单个文档，还是您还谈论模型的可重用性和在多个 API 描述文档之间共享点点滴滴？

原因之一是我们在设计上进行了很多迭代 :) 当这个问题被打开时，没有 MSON，我们仍然在嵌入与引用之间纠结。

但是为了记录，您在那里有什么需求？ 它只是多文件管理和编译单个文档，还是您还谈论模型的可重用性和在多个 API 描述文档之间共享点点滴滴？

我们有来自一堆端点的标准响应。 我们希望能够在一个地方定义它，靠近它所在的图书馆，然后将它导入到我们需要响应的地方。