Api-blueprint: モジュール性

おそらく企業内のさまざまなグループの管理下にある多数のAPIが存在する状況では、これは絶対的な天の恵みになります。

@rurounijonesは、この機能を明確にするために、「1つのAPI記述を複数のファイルに分割できるようにする」ことを意味します。

誰かがこれについて何か考えがありますか？ Drafterに関する以前のコメントによると、 https： //github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

オプションは、ブループリントの上部にいくつかのinclude / require機能を追加するか、ディレクトリからすべてのブループリントをフェッチしてそれらを連結することです。

考え？

連結は単純ですが、requireは必要に応じて使いやすく、その後に何かを追加する方が簡単だと思います。

これは、特許で定義されているかのようにファイルの内容を盲目的にインライン化するだけですか、それともファイルの内容に何らかの制限がありますか（たとえば、独自のyamlヘッダーを持つことができますか？親yamlと競合しますか？）制限はないほうがいい気がしますが、育てようと思いました。

@zdne

まず、単純なファイル連結を使用して、これをGruntですでに管理するための基本的なシステムがあります。 ブループリントは管理不能になりつつあり、これはファイルに分割するための迅速で汚い方法でした（ファイルシステムの順序によって連結されているため、任意の数のファイルに注意してください）。 ここに簡単な説明を付けてGruntfileを投稿しました。

連結は非常に簡単に実行できることを考えると、「公式」ツールの方が強力である必要があることは私には理にかなっています。 私はこれについてもっと考えていて、これが他のシステムによってどのように処理されるかについていくつかの研究をしようとしています。

1. 含める/必須
   
   
   
   • インクルードはファイルの先頭で行われ、ファイルの一部はファイル内で参照されます。 これには、現在の[Model Reference][]構文よりも堅牢な参照システムが必要だと思います。 理想的には、インクルードされたファイル内の任意のノードがアドレス可能であるため、 [github.Users.'Create A User'][]や[github][POST /users]などのノードが存在する可能性があります。 （ =のようなプレフィックスも必要になる場合があります）。 名前またはurl + method以外に、AST内の特定のノードを参照するためのより良い方法はありますか？
   
   
   • ノードの内容を逆参照するための優れた方法がある場合、これはCプリプロセッサを使用して実行できます。Cプリプロセッサには、追加コストなしで多くの追加機能が付属しています。
   
   
2. テンプレートシステム/トランスクルージョン
   
   
   
   • 非マークダウン-テンプレートは別のテンプレート言語で記述されるため、テンプレートファイルはsnowcrashで解析できません。 このような例としては、 grunt-readmeがあります。これは、ブループリントファイルをテンプレート化するために箱から出してすぐに機能するように見えます。
   
   
   • マークダウン-これは、製図の問題で説明した=[]()または:[]()構文のようなものになります。 それはまだ有効なマークダウンであり、snowcrashによって解析可能です。
   
   
3. 両方
   
   
   
   • ノード（ [github]['Create A User'] ）と直接トランスクルージョン（ :[/github.md](/github.md) ）を参照するための構文を定義すると、両方を簡単に使用できるようになります。 おそらく、それらは:[]()のような同じ一般的な構文を持つ可能性があり、パーサーはそれがノードであるかファイル参照であるかを判別します。
   
   

これについて何か考えはありますか？ いくつかのオプション/ツールがありませんか？ 私は、トランスクルージョンとノードの間接参照の共通の構文を持つ「両方」のオプションに傾倒していますが、おそらくそれは少し多いです。

連結は非常に簡単に実行できることを考えると、「公式」ツールの方が強力である必要があることは私には理にかなっています。

最終的にはそうかもしれませんが、私はそれを過度に設計せず、物乞いの中で無駄のないシンプルなものを展開したいと思います。

問題を見ると、対処する必要のある問題があります。主に次のとおりです。

1. 参照された（外部）アセット-＃20およびhttps://github.com/apiaryio/snowcrash/issues/57#issuecomment-28564071で説明されているように
2. ブループリントをより管理しやすい論理部分に分割する

分割の目的で、リソースグループまたはリソースのいずれかのみを検討します（たとえば、アクション、トランザクションの例、またはリクエストは考慮しません）。 少なくとも最初は。

広告1：_参照されたアセット_は＃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のようなもの

最初はこれで十分だと思いますか？

最初はこれで十分だと思いますか？

同意しました。 「アセット」を含めることと「リソース」/「リソースグループ」を含めることを区別していることに気づきました。 私はそれらすべてを自由に含まれる「ノード」として考えていました。

2番目のポイントとして、トランスクルージョンのために既存のMultiMarkdown構文を参照すると便利だと思いました。

This is some text.

{{some_other_file.txt}}

Another paragraph

これは、リソースを含める簡単な方法のように思えますか？ （または実際、任意のテキスト/ノード？）

だから私の意見を明確にするために：

1. 参照されるアセットの適切な構文は、説明したように:[]()または=[]()だと思います
2. トランスクルージョンに適した構文は、multimarkdownで使用される{{ }}だと思います。

また、いくつかの語彙を明確にするために、「包含」と言うときは、「トランスクルージョン」と言うときの意味を指していると思います。つまり、プレースホルダーを別のファイルのテキストに完全に置き換えます。

私が正しく理解している場合、「参照」と「包含」/「トランスクルージョン」の違いは、単に「レンダリング」のために、たとえばhtmlまたはpdfになります。 パーサーにとって、アセット（たとえば）が参照されているかトランスクルージョンされているかは関係ありません。同じASTが発生します。 あれは正しいですか？

1. 参照されるアセットの適切な構文は、次のようになると思います：または=説明したとおり
2. トランスクルージョンの適切な構文は、マルチマークダウンで使用される{{}}だと思います。

1つの方法だけでなく、両方を使用するのはなぜですか？ これら2つを構文的に区別することには何か利点がありますか？ 個人的には、プレーンなMarkdownでフォローできるようにレンダリングされるので、ナンバーワンが好きですか？

「包含」とは、「トランスクルージョン」とは、プレースホルダーを別のファイルのテキストに完全に置き換えることを意味していると思います。

同意します、これからトランスクルージョンを使用しようとします。 ありがとう！

私が正しく理解していれば、「参照」と「包含」/「トランスクルージョン」の違いは単にレンダリングのためです

あまり。 私の意見では、参照（参照の作成）は実際には出力（AST）へのリンクのみを追加し、残りはツールに残す必要があります（https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 ）。

Translcusionは、パーサー（またはプリプロセッサー）にコンテンツをプルするように指示する必要があります...

ここでの更新：これは確かに計画されており、非常に必要とされています。 私たちはこれを可能にするツールに取り組んでいます。 一方、Apiaryオンラインエディタに依存しない場合は、 https：//gist.github.com/danvine/11087404または別の同様のアプローチのようなものを使用できます（これについては、少なくともいくつかのgulpベースのツールを知っています）。

Whiskyは.apib拡張子をサポートするようになり、アウトラインビューで大きなMarkdownファイルの編集がはるかに簡単になりました：http： //vimeo.com/album/3108294/video/110486733

デスクトップアプリ（Mac用）が必要な場合は、 http：//9muses.se/erato/およびhttp://25.io/mou/も.apibをサポートします

RobertCrooksラーニングサービスディレクター
Brightcove、Inc

2015年12月29日午後4時8分、 KevinIngersollnotifications @ github.comは次のように書いています。

Whiskyが.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)
  ```

`` `` ``

コードブロックはパーサー/プリプロセッサーに対して不透明なままである必要があるためです。

また、トランスクルージョンはどのレベルでも機能するはずではないと思います。トランスクルージョンされるファイルは、それ自体が有効な青写真である必要があります。

これへの取り組みについては、機能ロードマップではかなり高いですが、ETAはまだありません。

これと機能のロードマップの可視性についてのコメントや考えをいただければ幸いです。

ありがとう！

トランスクルージョン構文はこれまでのところ最良の提案のようです。これはエレガントでクリーンなアプローチであり、これまでに見た他のどの提案よりも優れています。 Fwiw、私から+1。

これに関するニュースはありますか？

トランスクルージョンを使ったアプローチは私には良いように思えますが、不利な点は見当たりません。

とりあえず、Herculeと:[Gist](blueprint/gist.md)構文を使用することをお勧めします。 APIブループリント仕様とパーサーツールチェーンへのバックポートに向けて機能します

この問題に対して何かしましたか？ また、大きなapibファイルを複数に分割したいと思います。
ありがとう！

ねえ@ adams-sarah残念ながら私の側からではありません。 Hercule（https://github.com/jamesramsay/hercule）は非常にうまく機能するため、引き続き使用することをお勧めします。唯一の欠点は、Apiary.ioで複数のファイルを編集できないことです。 なんとかお手伝いできるか教えてください！

ヘラクレスの使用に+ 1https：//github.com/jamesramsay/hercule
私たちはしばらくの間それを使用してきました、そしてそれがまだapib仕様にその道を見つけることを願っています

：+1：この機能の追加。

また、単一のTOC /インデックス手法もサポートしています。 トランスクルージョンは少し柔軟性があり、私の過去の経験では、大きなwikiベースのドキュメントではスケーリングされていません。

ソースマップをサポートするには、これをパーサー自体に確実に組み込む必要があります。

その間に、Herculeの使用方法を示す実際の例を用意しました– https://github.com/apiaryio/api.apiblueprint.org

@zdne （interagent / prmdを介して）json-schemaの使用法では、リソース行に沿って分割し、基本的に特定のディレクトリ構造を適用して、包含を暗示します（多かれ少なかれ、ディレクトリ内のすべてのものを含むトップレベルのスキーマを構築します。サブスキーマなので、物事のレベルが変わります）。 これは明らかに私たちが行っていたことにかなり特化しており、あなたの場合には特に適切ではありませんが、私たちの経験を共有したいと思いました。 それと比較して、トランスクルージョンははるかにエレガントで柔軟に見えると思いますが、統合された目次/インデックスを持つためのいくつかの簡単な手段もあると間違いなく素晴らしいでしょう。 たぶんそれは私たちがやったことと似ています。つまり、このインデックスとして機能するuberブループリントを作成し、その中のサブブループリントをトランスクルージョン/参照します。 私はそれが自動的に良いこととして起こることを見ることができますが、それがあなたが望むことをうまくやらない場合には厄介であることもわかります。 とにかく、それが役に立ったら、私は私の経験をさらに議論/共有したいと思います。

この機能のステータスは何ですか？
Apiary.ioでProプランを使用しており、この機能が必要です

@DavidBM私も同じ問題を抱えていました。 これを回避する方法は、2つの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でカスタマイズされたソリューションがありましたが、養蜂場のプロにお金を払うことのポイントは、製品マネージャーがgitを入力せずにドキュメントを更新できるようにすることです。 これは私たちにとって完全なブロッカーであると思います。これが解決されない場合は、Apiaryとの契約をキャンセルします。

ヘラクレスや他のツールを長い間利用できた後、これがこの状態になるとは思いません。

これは非常に残念です:(

みなさん、こんにちは。遅くなってここに来て、古いものを再開して掘ってごめんなさい。 これが適切な場所でない場合は、ご容赦ください。 しかし、青写真のモックを開発するための調査を行っていると、この議論を見つけました。これは、これまでに見つけたものに最も近いものです。

モデルごとに応答を分割するのに苦労しています:(。モデルを別のフォルダーに参照することはできませんか？
ブループリントフォルダー内にすべてのリクエストを入れ、たとえば、別のモデルフォルダーに、すべてのエンティティモデル（MSON / MD / JSON /適切なファイル）を入れて、さまざまな応答に簡単に再利用できるようにします。 誰かがこれを成功させていますか？

この問題が注目されたら本当に素晴らしいと思います。 APIブループリントには26000行あり、管理が非常に困難です。

Dreddを使用してコントラクトテストを実装しており、Aglioを使用していますが、これが追加された場合は、追加する必要がないので便利です。

その理由の1つは、設計を何度も繰り返していることです:)この問題が開かれたとき、MSONはなく、トランスクルージョンと参照の違いに悩まされています。

しかし、記録のために、そこにあなたのニーズは何ですか？ それは単にマルチファイル管理と結果としての単一のドキュメントのコンパイルですか、それともモデルの再利用性と複数のAPI記述ドキュメント間での断片の共有について話しますか？

その理由の1つは、設計を何度も繰り返していることです:)この問題が開かれたとき、MSONはなく、トランスクルージョンと参照の違いに悩まされています。

しかし、記録のために、そこにあなたのニーズは何ですか？ それは単にマルチファイル管理と結果としての単一のドキュメントのコンパイルですか、それともモデルの再利用性と複数のAPI記述ドキュメント間での断片の共有について話しますか？

多数のエンドポイントからの標準的な応答があります。 それを収容するライブラリの近くの1つの場所で定義し、応答が必要な場所にインポートできるようにしたいと考えています。