api-blueprint 🚀 - 外部資産

私はこの機能に興味があり、理想的には後でではなく早く追加したいと思っています。

私たちの特定のユースケースは、リクエストとレスポンスの本文がApacheAvroによって生成されたバイナリ構造であるAPIを文書化するためのものです。これらのリクエスト/レスポンスでは、「スキーマ」をAvroスキーマ定義ファイル、またはそのAvroスキーマを説明する生成されたHTMLドキュメントへのリンクにすることができます。次のようになります。

## POST /myresource
Creates a new myresource.

+ Request (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)
+ Response 201 (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)

davidmc24 2013年10月21日

👍5

：+1：

mhurne 2013年10月21日

@mhurne @ davidmc24 ASTでのこの機能の表現について考えたことはありますか？ ASTのハイパーリンクを確認しますか、それともブループリントパーサーがターゲットURLをフェッチし、そのコンテンツをASTに埋め込むことができるようにする必要がありますか？

netmilk 2013年10月21日

私の期待は、ASTにはハイパーリンクの内容ではなく、ハイパーリンクが含まれることです。たとえば、リンクをHTMLドキュメントで作成できるように、ASTが直接コンテンツではなくハイパーリンクであることを「認識」すると便利な場合があります。

APIからスキーマを外部化することを選択した場合は、スキーマが大きすぎてAPIドキュメントにインライン化できないか、スキーマが複数のAPIで使用されており、独自の信頼できるドキュメントがあるか、スキーマは、埋め込みに適さない形式です。これらの例はスキーマ固有ですが、他のペイロードタイプにも同様の理由が当てはまると思います。

davidmc24 2013年10月21日

@ davidmc24

私はそれが好きです。ハイパーリンクだけの場合は、パーサーに実装するのはおそらくかなり簡単です。

ただし、より大きな課題は、ASTとそのメディアタイプに必要な変更を伴うことです。

おそらくこのようなものに：

{
  "name": "<name>",
  "description": "<description>",
  "headers": {
    "<header>": {
      "value": "<header value>"
    }
  },
  "body": {
    "content": "<body>",
    "href": "<uri>"
  },
  "schema": {
    "content": "<schema>",
    "href": "<uri>"
  }
}

zdne 2013年10月22日

うん、それはまさに私が考えていたASTです。

davidmc24 2013年10月22日

さらに、 Drafter apiaryio / snowcrash＃57によって埋め込まれる（参照リンクだけでなく）外部アセットの構文を追加します。

:[file.json](path/to/file.json)

また

=[file.json](path/to/file.json)

または、Mardkown _implicit link name_を使用します。

:[path/to/file.json]()

また

=[path/to/file.json]()

zdne 2014年01月31日

👍3

こんにちは、
外部リンクを持つ別のユースケースは次のとおりです。APIの属性の定義/説明を、すべてのドキュメントで使用されるマスター用語集のそれぞれの定義にリンクしたいと思います。これにより、すべてのドキュメントを最新の状態に保ち、同期を保つための扉が開かれると思います。それ以外の場合は、APIドキュメントを更新する必要があります。個別に、定義が同期しない余地を残します。

angie2014 2014年05月28日

Markdownは、ほとんど互換性のある拡張機能の不快な緩い結合ファミリーであるため、わかりませんが、リンクのような構文が実際に「参照ではなく埋め込み」を意味する場合は、画像構文（！ sigilを使用）のみです。： ![Alt text](/path/to/image.jpg "Optional Title") 、これはGruberの元の仕様の一部です。 Zの提案は、とりわけこの構造に違反しています（ファイル名が間違った場所にあります）。準拠する方が良いのではないでしょうか。それ以外の場合は既存の構文に新しい印章を使用するだけです。

jrep 2014年05月30日

良い点@jrep ！

準拠する方が良いのではないでしょうか。それ以外の場合は既存の構文に新しい印章を使用するだけです。

それが私の目標です。

Gruberによると、次のことは同じ目標を達成するはずです。

[label](path/to/image.png)

[alt text][label2]
[label2]: path/to/image.png

[label3][]
[label3]: path/to/image.png

label 、 alt text 、およびlabel3は理論上存在しませんが、レンダリング後に要素は表示されません。

私は私のポイントを推測します

=[path/to/file.json]()

する必要があります

=[path/to/file.json][]

ここで、lablelは実際のURLであるため、適切な完全定義（マークダウンが正しくレンダリングされるようにするため）は次のようになります。

=[path/to/file.json][]
[path/to/file.json]: path/to/file.json

今、書くのは明らかに退屈でしょう：

[path/to/file.json]: path/to/file.json

質問は–これ（ラベルを定義する）はパーサーによって暗黙的に想定されるべきですか？それとも、ブループリントの作成者に[alt text](URL)構文を使用するように依頼する必要がありますか？

zdne 2014年06月02日

リンクが人間が読めるように、実際に_アセットが何であるかを説明する_ためにalt / label部分を使用することはできませんか？ =[file.json](path/to/file.json)ようなものを書くのは不必要に退屈なようですが、 =[Schema for notes](path/to/file.json)は私には問題ないようです。青写真の作成者に、青写真を読者にとってわかりにくいものにするように勧めます。実際には、アセットが欠落している場合や、正確にリンクされているものが自明でない場合があります。 alt属性は、まさにこの場合のために考案されたと思います。

誰かがこれを回避して、この方法でアセットを説明するベストプラクティスを無視したい場合は、いつでもダミーテキストをそこに置くことができます（すでに述べたfile.json ）。

例として=構文を使用しましたが、同じことが!当てはまります。

honzajavorek 2014年06月02日

直接リンク、明示的または暗黙的なラベルなど、使用される構文に関係なく、追加のシジルを使用してマークダウンをサポートする必要があると思います。

これに同意する場合、2つの質問だけが残ります。

使用する印章
例/チュートリアルで使用するWhetスタイル

私の意見では、 Schema for notesようなラベルに注意してください

=[Schema for notes](path/to/file.json)

ほとんどの場合、 Notesリソースのスキーマセクションで使用するため、これも重複しています。

例えば：

# Notes [/notes]
## GET 
+ Response 200
    + Body
         ...
    + Schema
        =[Schema for Notes](path/to/file.json)

考え？

zdne 2014年06月02日

私はすべての標準バリアントをサポートすることに全力を注いでいますが、これは次のとおりです。

= [path / to / file.json] []
[path / to / file.json]：path / to / file.json

...私がGruberの定義を理解する方法ではありません。むしろ、私はhonzajavorekに同意します。最初の[]にあるものは、リンクテキストの冗長で面倒な複製ではなく、何らかの形で人間が読めるタグです。したがって、そこにパスを含めることは構文的には有効であるように見えますが、（a）奇妙で、（b）役に立たないです。

意図が「新しい印章を備えたGruberで有効なリンク形式」である場合、私はそのセマンティクスが好きですが、それほど驚くことではない例を提案します（honzajavorekと私が提案した種類の）。

jrep 2014年06月03日

@ jrep @ honzajavorek同意します。

zdne 2014年06月03日

画像またはリンクのいずれかについて、アセットの包含を既存のパターンと比較するのは難しいと思います。それは実際にはそれら2つの組み合わせではありませんか？

画像構文のアナロジーの問題は、画像の世界では代替テキストが重要であり、通常、特定のコンテキストで重複することはなく、実際に![img.jpg](/path/to/img.jpg)書きたくないということです。コンテンツ管理システムと「怠惰な」だけです。人々はこれをします。代替テキストを要求することは、良い習慣を教えることです。

しかし、資産は必ずしも代替テキストを必要としません、それは本当です。 @zdneが述べたように、これらは常に、ここで何が起こっているのかが完全に明確になるようなコンテキストで使用されます。私はそれに同意します。問題は、私が考えることができる唯一のアナロジーは、ラベルのないリンクです。

[Google](http://www.google.com)対...

<http://www.google.com> （ Gruber ）
http://www.google.com （今日のMarkdownの現実だと思います）

ハイブリッドなものが必要な場合は、それを「画像の自動リンク構文」と呼びましょう。可能な限りGruberに準拠したい場合は、次のようなものが必要です。

=[Alternative text about assets](/dev/null) ←誰もがこれに精通している、これは例にあるはずです（_それは画像のようで、理にかなっています！_人々の頭の中で飛び出します）
=[Alternative text about assets][id] ←同じアセットを複数の場所に含める場合
=</dev/null>または<=/dev/null> ←自動リンク構文（_...画像の自動リンク構文はどのようになりますか？_）、Gruberの自動リンクのバージョンは誰にもわかりません（リンクはどこでも自動的に変換されるため、 < sと> s）ですが、本当に代替テキストが必要なく、それに悩まされている場合は、これを使用する方法を学ぶことができます。

ここでも、例として=を使用します。私の意見では、これらは最も読みやすく、少なくともGruber風のソリューションです。たとえば、私は考えます

[label3][]
[label3]: path/to/image.png

読者としての私にとってはかなり不可解であり、既存のMarkdownの使用法の現実に従わないこと。私はそのような可能性についてさえ知りませんでした、私はペアリングがブラケットの2番目のカップルによって行われなければならないと思いました。（しかし、私はこの最後の段落が非常に主観的であることを完全に承知しています）。

honzajavorek 2014年06月03日

@zdne ：=は問題ないようです。

@zdne ：最も可能性の高いテキスト=[IN HERE](schema.json)は、私が考えることができるブループリントの使用法では冗長であることを認めます。ここではブレーンストーミングだけですが、その冗長性を活用して文法を単純化するとどうなるでしょうか。つまり、置き換えます

# Notes [/notes]
## GET 
+ Response 200
    + Body
         ...
    + Schema
        =[Schema for Notes](path/to/file.json)

と

# Notes [/notes]
## GET 
+ Response 200
    + Body
         ...
    + =[Schema for Notes](path/to/file.json)

@honzajavorek ：Blueprintがそれらの場所で文字列 "/ dev / null"を許可/義務化することを実際に提案していますか？それとも単なるプレースホルダーでしたか？

私も「参照リンク」を使用することはありませんが、Blueprintがそれらを引き継ぐことに反対するつもりはありません。

jrep 2014年06月03日

@jrepプレースホルダーとして/dev/nullを使用しました:)

セクションヘッダーで直接リンクを使用しても、実際にはまったく悪くはありません。もちろん、それは一見しただけで、私はそのようなことの短所が何であるかについて本当に考えていませんでした、しかし...一見それは私に魅力的であるように見えます。

honzajavorek 2014年06月03日

@jrep私はそれが好きです。

さらに進んで

# Notes [/notes]
## GET 
+ Response 200
    + =[Body](path/to/body.json)
    + =[Schema](path/to/schema.json)

zdne 2014年06月04日

ファイルを個別のファイルに分割してからインポートする機能は、長い冗長APIに非常に役立ちます。

中間期には、私は自分の青写真プロジェクトをうなり声で管理します。私はgrunt-importを使用しており、 index.source.apibファイルは主に<strong i="7">@import</strong> "/include/section.apib";

次に、 grunt watchを実行するだけで、ファイルを保存するとすぐに、gruntがindex.source.apibファイルを「index.apib」に再コンパイルします。これもaglioによって監視されており、ブラウザが次のように更新されます。リアルタイムでレンダリングを見せてください。

セットアップには5分かかりますが、生活がとても快適になります。：+1：

alexborisov 2014年08月30日

@alexborisovそれはかなりきちんとしています！共有していただきありがとうございます。私が（他の場所で）言ったように、私たちはパーサーハーネスツールの作業を開始しました。これは最終的にこれを処理する必要があります。

また、その価値のために、複数のブループリントを1つに構成し、Apiaryクライアントgemhttps ： //gist.github.com/danvine/11087404を使用して公開するスクリプトを次に示します

zdne 2014年09月01日

@alexborisov 、それは本当に賢い

skawaguchi 2014年11月24日

@skawaguchi gulp -file-includeを使用してgulpタスクを作成し、jsonを監視してAPIを構築できます。唯一の欠点は、api.mdを生成するためにapi.source.mdが必要なことですが、IMOは少額の支払いです。

ghost 2015年02月24日

また、 @ jamesramsayのHerculeをチェックアウトする価値があるものについては– https://github.com/jamesramsay/hercule

zdne 2015年02月25日

言及してくれてありがとう@zdne 。 APIドキュメントを作成するときにも同様の課題があり、過去3か月間Herculeを社内で使用しています。

Herculeは、単純な{{filename.md}}パターンを使用して含めます。

ほぼ同じリソースを持つさまざまなタイプのAPIコンシューマー用のAPIコンテキストが多数あり、さまざまなドキュメント間の重複を減らすことに熱心でした。したがって、この構文を拡張して、以下もサポートします。

{{entity.json links:role-links.json}}

{
  "id": 123,
  "name": "example",
  "links": {
    {{links}}
  }
}

{{links}}プレースホルダーは、その親ファイルの1つによって指定されたターゲットファイルを持つことができます。これは、ほぼ同じ大規模なスキーマに役立つことがわかりました。

jamesramsay 2015年02月26日

@jamesramsay

Markdown独自の[<placeholder>](link)の代わりに{{link}}構文を使用する理由を知りたいだけですか？上で議論したように。例えば：

=[gist](gist.apib)

また

:[gist](gist.apib)

それは同様に機能し、マークダウンとして合理的にレンダリングされるので、リンクをナビゲートすることができ、 `[placeholder]リンクオプションで[placeholder][]などのはるかに豊富な構文を使用できます...

zdne 2015年02月27日

@zdneこれは本当に素晴らしい提案です！残念ながら、6か月前にこのスレッドを見ていませんでした。

{{link}}構文は、 MultiMarkdown4のトランスクルージョン構文に基づいていました。それはトリックを行い、私は新しい構文を発明していませんでした。

当時、私はMarkedアプリ（ <<[link] ）と他のいくつかのMarkdownコンパイラーも調べました。

Githubでソースドキュメントを表示するときにリンクをクリックできるという利点と、Markdownの感触との一貫性が向上したため、 :[gist](gist.apib)を使用するようにherculeを更新しました。誰かがそれを試してみたいなら、それはNPMにあります。

jamesramsay 2015年03月04日

やあみんな、私は内部プロジェクトにaglioでAPI Blueprintを使用しています、そしてAPI Blueprintは現在を含むファイルをサポートしていないので、aglioは構文でファイルを実装します、この機能のおかげでリクエスト/応答を分割できますAPIドキュメントからのJSONデータは明確ですが、分離されたJSONデータファイルを整理すると、同じ部分を再利用する適切な方法がまだ不足していることがわかります。たとえば、 user_model.jsonます。

{
    "username": "alice",
    "comments": [
        {
            "id": 1,
            "content": "hello"
        }
    ]
}

およびcomment_model.json ：

{
    "id": 1,
    "content": "hello"
}

コメント部分user_model.jsonあるといつもと同じでなければなりませんcomment_model.jsonので、JSONファイルが互いを含めることができるメカニズムがある場合、彼らの一貫性を維持することは非常に容易になり、表彰モデルが変更された場合でも、どこでも変更する必要はありません。

しばらく考えて、JSONファイルをサポートする構文を作成してみます。これが私の努力です。
Python実装のインクルードsytanx： https ：

前の場合の構文は次のようになります。

{
    "username": "alice",
    "comments": [
        {
            "...": "include(commend_model.json)"
        }
    ]
}

{ "...": "include(commend_model.json)"}を使用して、 commend_model.jsonファイルへのインクルードを表します。

APIブループリントの特殊なケースではありませんが、インクルード機能を備えたJSON自体を考えようとするのはかなり一般的なことです。これは、APIブループリントでも使用できると思います。

見て、いくつかの提案をしてください。現在、このjson-includeは私のプロジェクトのいくつかで正常に機能しています。それが良くて意味があるかどうかを自分で判断できないので、それについての考えは非常にありがたいです：）

reorx 2015年04月28日

ねえ@reorx ！アイデアを共有していただきありがとうございます。最近、APIブループリントで（だけでなく）データを記述するための構文であるMSONの（ベータ）を

あなたの例を使用すると、それは次のように機能します：

# Data Structures

## User 
- username: alice
- comments (array[Comment])

## Comment
- id: 1
- content: hello

次に、JSONとしてレンダリングするように依頼できます。

# Resource [/r]
## Retrieve [GET]
+ Response (application/json)
    + Attributes (User)

どう思いますか？これはあなたを助けますか？

zdne 2015年04月28日

この機能はパイプラインのどこかにありますか？それは私たちにとってとてもいいことです。
ブループリントを使用してメソッドを記述しますが、JSONスキーマは個別にホストされます。現在、リクエスト/レスポンス要素ではサポートされていないため、メソッドの説明にリンクとしてスキーマを含める必要があります。
実際に最も理想的なのは、request / response要素の下のリンクを使用してJSONスキーマWebページを「インクルード」できる場合ですが、ドキュメントページのロード時に何百ものインクルードを行わないように、レイジーロードする必要があります。

jonathancrosmer 2015年08月20日

リクエスト/レスポンスの本文の例や定義スキーマファイルの外部参照を含めることができないという事実は、Blueprintが他のAPI定義言語に関して持つ_非常に_大きな欠点の1つだと思います。

mariusor 2015年11月17日

+1

moon0326 2015年11月21日

@jonathancrosmer @lpbm @ moon0326

特にhttps://github.com/jamesramsay/herculeを確認して

https://github.com/jamesramsay/hercule/blob/master/examples/api-blueprint/gist-fox.apib

と

https://github.com/jamesramsay/hercule/blob/master/examples/api-blueprint/blueprint/gists.md

これはあなたのために働きますか？

zdne 2015年11月24日

@zdne私は

これらの2つの例はあまり示していません。私は何を見ていますか？

moon0326 2015年11月24日

@zdne ：はい、.md / .apibでもxmlでも、あらゆるタイプの外部リソースを含めることができる限り、jsonは問題ありません。

それは養蜂場が実装するものですか、それとも養蜂場にコミットする前にヘラクレスを使用するように私たちにアドバイスするメッセージですか？

mariusor 2015年11月24日

以前、ブループリントを複数のファイルに分割する（および外部アセットを使用する）ためのソリューションのリストを用意しました： https ：//gist.github.com/zdne/137396a1c2d45f75b306

@jamesramsayは、青写真を複数の部分に分割するために使用したい構文を実装する素晴らしいHerculeツールをまとめました。

外部資産については。 Herculeはそこでも機能しますが、これが最終的な構文であるかどうかはわかりません。特に

それでも、Apiary内での編集に依存しない場合は、今日Herculeを使用してこの機能のほとんどを取得できます。

それはApiaryが実装するものですか？

はい、 :[](url)構文に基づいてトランスクルージョンを実装したいと思います。ここでの落とし穴は、Apiaryエディターと「ファイルシステム」の実装です。それまでは、Herculeを使用して、連結されたファイルをApiaryにプッシュする必要がありました。

これは明確ですか？

zdne 2015年11月25日

👍1

ここでの落とし穴は、Apiaryエディターと「ファイルシステム」の実装です。

たぶんあなたはURLを使ってそれを回避することができますか？

mariusor 2015年11月25日

ドキュメントをフェッチするためにおそらくはい、しかし編集のためではありません。

zdne 2015年11月25日

現在、Apiaryに接続されているgitリポジトリにApiaryブループリントが保存されています。ブループリントには、JSONスキーマをホストする内部サーバーへのリンクが多数あります。
このソリューションでは、元のMarkdownファイルがあり、Gitフックなどを使用してトランスクルージョンを実行し、同期されたブループリントとして結果をコミットすると思います。それがうまくいくように聞こえます。トランスクルージョンプロセスを設定するのは少し面倒ですが、うまくいくとスムーズになるので、調べてみます。ありがとう！

jonathancrosmer 2015年11月25日

@lpbm Herculeは、ローカルファイル（相対ファイルパス）とリモートファイル（URL）の両方のトランスクルージョンをサポートし、「マークダウントランスクルージョン」とラベル付けされていますが、任意のテキストファイル（.md、.apib、.json、.xmlなど）をサポートする必要があります。一部の人々がHerculeを使用しているのと似ている可能性のあるユースケースの1つは、アプリケーションによって生成されたJSONスキーマをHTTP経由でトランスクルージョンすることと、ドキュメントのドライネスを高めるためのローカルファイルトランスクルージョンです。

@jonathancrosmerのスポット-内部CI環境でJenkinsを使用して同様のことを行います。 Adslotでは、コミットがいずれかのブランチにプッシュされるたびに、単体テストとともにAPI BlueprintをHerculeでコンパイルし、それをdreddに渡します。すべてが合格した場合、デプロイタスクの一部として、オプションでApiaryにプッシュできます。当初はAPIドキュメントに変更が加えられるとすぐにApiaryに直接プッシュしましたが、機能スイッチなどを使用してより大きなリリースで作業しているときに問題が発生することがあることがわかったため、現在はアプリケーションと一緒にデプロイしています。

jamesramsay 2015年11月25日

プレーンURIの指定を許可するだけではどうでしょうか。レンダラーは、URIをリンクにレンダリングするか、その内容をドキュメント出力に含めるかを決定できます。これにより、さまざまなMarkdownフレーバーを処理する手間も省けます。

bartfeenstra 2016年05月20日

プレーンURIの指定を許可するだけではどうでしょうか。

そうあるべきです。 [label](URI)は、転写に使用し、適切にレンダリングする必要があります。違いは、transclustionツールの場合は:[label](URI)かどうかをマークする必要があることです。

zdne 2016年06月09日

やあ、

これに関するニュースはありますか？
スキーマと例は、APIドキュメントの本体から分離して、サーバーやクライアントが検証や単体テストに使用できるようにする必要があると思います。リンクは大丈夫です。

乾杯、

タマス

smil2k 2017年12月11日

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

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

clucasalcantara 2018年08月05日

Api-blueprint: 外部資産

最も参考になるコメント

全てのコメント43件

関連する問題