問題タブ [apiblueprint]

「curl-able」になるように設計された小さな Web サービスを作成したので、リクエストのapplication/x-www-form-urlencodedパラメーターに依存します。POST

Apiaryを使用してこのサービスを文書化したいのですが、これらのパラメーターの構造化された文書を提供する方法を見つけることができませんでした。このようなリクエストの例を提供できます...

...しかし、これにより、個々のパラメーターに関するドキュメントを提供することはできません (また、さまざまなパラメーターの入力フィールドを提供できないため、養蜂場コンソールでのテストには適していません)。

API ブループリントの仕様を何度か読みましたが、適切な解決策を見つけることができませんでした。これらのパラメータの構造化されたドキュメントを提供する方法はありますか?

API ブループリントを使用して RESTful 検索 API の API ドキュメントを開発しています。フィルターを API に渡して組み立てられるようにしたいと思います。

この質問に従って、私はパーセントでエンコードされた角括弧を使用していますが、この質問とは異なり、考えられるすべてのキー名を説明することはできません。

Blueprint API ドキュメントを作成するときに、URL でハッシュベースのパラメーターをフォーマットする方法は?

ソースデータの任意のフィールドになる可能性があるため、キー名を可変にしたいと考えています。これは機能しますか？

このような 2 次元配列の推奨形式はありますか? + filter_field実際には一致しないため、これは Dredd では機能しないようです。filter[filter_field]

API ブループリントの仕様を読むと、次のように「データ構造」を指定できるように設定されているようです。

• 住所
  • 通り: 100 Main Str. (文字列) - 番地
  • zip: 77777-7777 (文字列) - zip / 郵便番号

...

• お客様：
  • ハンドル: mrchirpy (文字列)
  • 住所: (住所)

次に、モデルで、データ構造への参照を作成します。

• モデル

  [お客様][]

データ構造を参照することにより、エンドポイントに沿ってドキュメントと例を生成する必要があるようにすべて設定されているようです。

ただし、それを機能させることはできないようです。また、「完全に正規化されたデータ抽象化」を使用した例を見つけることもできません。データ構造を一度定義してから、どこでも参照したいと考えています。ツールに問題があるようです。具体的には、レンダリング エージェントとしてaglioを使用しています。

これはすべて折り畳みタイプのもののトップになるように思われるので、私は混乱しており、何かが欠けているのか、ここで何が可能かについて間違った仮定をしているのか疑問に思っています.

仕様の新しい Attributes セクションと DataStructures セクションを使用して、API ブループリントでエンドポイントを文書化しようとしています。

私のリクエストペイロードは次のようになります。

私の応答ペイロードは次のようになります。

次の API ブループリント マークダウンを試しました。

これを Apiary で見ると、これは有効な API ブループリント ドキュメントであることがわかりますが、JSON がリクエストとレスポンスをどのようにプレビューするかはわかりません。このような構造は、API ブループリントで表現でき、Apiary で適切にレンダリングできますか?

Apiary ブループリントの例の中に次の Action セクションを見ました。ユーザーが間違ったパラメーターを渡したときに HTTP ステータス 404 で応答したい。たとえば、ユーザーが /questions/1 の代わりに /questions/xyz を渡した場合などです。ご覧のとおり、/questions の後のパラメーターは数値でなければならないことを定義しましたが、数値の代わりに xyz を渡すと、同じオブジェクトで応答します。

完全なコードを書いてください。前もって感謝します。

私は現在、そのような API の設計図を持っていますが、適切なレンダリングを実現できません。

私の質問は次のとおりです。

• 主に、リクエストとレスポンスのペイロードのテーブルが必要です。私はレイアウトを実現したいと思います: "Response" -> 応答のペイロードとして来る json オブジェクトのフィールドを持つテーブル。「+ Attributes」を入力すると表示されましたが (設計図を参照)、ペイロードとして json オブジェクトがある場合、これが状況を説明する正しい方法であるかどうかはわかりません。たぶん、他のキーワードを使用する必要がありますか？

• 「+ SampleProperties(SamplePropertiesDTO)」と記述されたフィールドでテーブルをレンダリングすると、オブジェクト型の SampleProperties としてテーブルの行としてレンダリングされたページに表示され、SamplePropertiesDTO の内容はレンダリングされたページのどこにもありません。ただし、すべてのデータ構造が配置されている場所など、インラインまたはドキュメントの別のセクションとして存在する必要があります。

• 可能であれば、データ構造オブジェクトのテーブルを個別に明示的に表示したいと考えています。現在、データ構造セクションは画面に表示されていません。どうすればそれができますか？

In my WebAPI being desinged, I have urls such as

and I need to specify another method with POST and same base URL, that does things similarly to original, but accepts different payload and returns different payload. At the moment I have

"modification" but I am not sure it is a good API practice. What would be the best way to design a modifier for method without necessity to change the resource URL? What would be the best practice - use another HTTP verb, add ?optionalparameter to URL, or something else?

以下のような X-Auth-Token ヘッダーを送信する必要があるサービスがいくつかあります。

API ブループリント標準に従って、API ドキュメントでこれを指定できるようにしたいと考えています。ただし、 API ブループリント ヘッダー セクションの定義から分かることから、 リテラル値 (例: Accept-Charset: utf-8) のみを指定でき、ヘッダーがどのように見えるか (例: のようなものX-Auth-Token (string)) のスキーマは指定できません。

Traits がこの問題の解決に役立つかもしれないという印象を受けましたが、現時点では少し頭を悩ませています。特定のアクション (またはアクションのセット) へのすべてのリクエストに X-Auth-Token ヘッダーが必要であることを指定する方法を誰か教えてもらえますか?