VSCodeのREST Clientというお手軽にHTTPリクエストを呼び出せる拡張機能があります。
基本的な使い方は、 拡張子が .http のファイルを作成するとVSCode上からリクエストを送ることができます。
一つのファイルに複数のリクエスト定義を記載し順番に呼び出すこともできます。
これはこれで便利なのですが、説明などを追加してドキュメントとしても管理できないかなぁと思っていたところ、実は Markdown ファイルにも対応してました。
コードブロックに http もしくは、rest をつけるとVSCodeからリクエストを送信できます（Markdownのプレビューからは呼べません。あくまで編集画面からです）。
これにより、API実行支援もついた可読性が高いドキュメントとして管理できます。
サンプル
「Send Request 時に入力を要求する @prompt 1」や 「.env 2」を使ってより汎用性を高めてます。
# ユーザー追加手順
以下を実行し、トークンを取得します。
取得したトークンは、`.env` ファイルの `TOKEN` に設定してください。
```http
# @prompt username
# @prompt password
POST http://example.com/api/get_token
{
"username": "{{username}}",
"password": "{{password}}"
}
```
以下のAPIで現在のユーザー一覧を取得します。
```http
GET http://example.com/api/users/
Authorization: {{$dotenv TOKEN}}
```
ユーザーを追加するAPIを実行します。
```http
POST http://example.com/users/
content-type: application/json
Authorization: {{$dotenv TOKEN}}
{
"name": "Bob",
"age": "{{$randomInt 1 50}}"
}
```
追加されたことを確認します。
```http
GET http://example.com/api/users/
Authorization: {{$dotenv TOKEN}}
```
以上
