9

API ブループリントを試してみたところ、よくわからないことがいくつかありました。

1. POST 本文のパラメーターを文書化するにはどうすればよいですか?

ありますが+ Parameters、クエリパラメーターを文書化するだけです。POST API を記述したい場合、POST パラメーター (application/x-www-form-urlencoded) を文書化することはできません。同じことが JSON にも当てはまります (#3 を参照)。

2. 応答に説明を追加する方法はありますか?

私は試した

+ Response 403
If the request request is made with HTTP instead of HTTPS.

しかし、これは本文のレスポンスとしてテキストを追加するだけです。

3. 回答のさまざまなフィールドについて説明してください

JSON を返す場合は、各フィールドを個別に、そのタイプと目的について説明したいと思います。それを行う方法はありますか？

ありがとう！

4

1 に答える 1

9

#1 と #3 は密接に関連しているため、一緒に見てみましょう。

ペイロード フィールドの説明

現在、ペイロードの実際のフィールド(モデル、応答、または要求) を議論するための専用の構文はありません。

今のところ、好きな Markdown 構文を使用してどのように記述するかはあなた次第です。

計画は、次のようにこれらのフィールド/パラメーターを議論するための Markdown 構文を提供することです:

JSON:

{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}

および設計図でのその説明:

- id: 1 (integer) - The unique identifier for a product
- name: A green door (string) - Name of the product
- price: 12.50 (number)
- tags: home, green (optional, array of strings)

私は現在これに取り組んでいます。詳細については、こちらをご覧ください。

レスポンスの説明

マークダウン形式のディスカッションをペイロードに追加することができます

# Resource [/r]
## List [GET]
+   Response 200

    This response will list the R

    + Body

            { ... }

詳細はこちら: https://stackoverflow.com/a/19433269/634940

注: Apiary で説明が正しく表示されるようにするには、New Apiary Rendered ドキュメントを使用する必要がある場合があります。

于 2014-05-20T21:07:13.073 に答える