Tools reference

list_endpoints、get_endpoint、lint_spec、diff_specs、contract_test。入力・出力・レスポンス例です。

list_endpoints

カタログ内のすべてのエンドポイント(method、path、summary)を、リクエスト/レスポンスの詳細なしで一覧表示します。get_endpointを呼ぶ前に何が存在するかを把握するのに使います。

オプションのfilterパラメータ: path、summary、tagsに対する大文字小文字を区別しない部分一致です。

text
GET /
POST /auth/register — Register
POST /auth/login — Login
GET /auth/profile — Get profile

get_endpoint

methodとpathを指定して、1つのエンドポイントの完全なCopy for AI形式のテキスト(Purpose、Request、Parameters、Validation、Success Response、Error Responses)を返します。

text
Endpoint: POST /auth/login

Purpose:
Login

Request:
{
  "email": "string",
  "password": "string"
}

Validation:
- email must be valid

Success Response (201):
{
  "success": "boolean",
  "data": { "access_token": "string", "user": { "id": "string", "role": "string" } }
}

Error Responses:
400 Bad Request

lint_spec

読み込まれたカタログに対して、スペック品質の問題(summary/descriptionの欠落、tagsの欠落、4xx/5xxレスポンスの欠落、レスポンスの説明未記載、operationIdの重複)をチェックします。

text
✖ POST /auth/login: [missing-description] no description declared
✖ POST /auth/login: [no-error-response] no 4xx/5xx response declared

diff_specs

読み込まれたカタログを別のスペック(ローカルファイルのpathまたはurlで指定)と比較し、追加・削除されたエンドポイントと、Breakingかどうか・Informationalかどうかのフィールド変更(新しい必須パラメータ、requestBodyが必須になった、削除されたレスポンスコード)を報告します。

text
+ POST /users
- DELETE /users/{id}
! GET /users/{id}: parameter "id" (path) is now required

contract_test

読み込まれたスペックから構築された、すでに稼働中のサーバーのすべてのエンドポイント(またはフィルタリングされたサブセット)に対して実際のリクエストを発行し、各ライブレスポンスを宣言済みのスキーマに対して検証します。セットアップ不要のPostmanコレクションランナー相当です。

baseUrl、オプションのheadersリスト(繰り返し指定可能な「Name: value」形式の文字列、例えば認証情報)、そしてサブセットをテストするためのオプションのfilterを受け取ります。

text
✓ GET /users (http://localhost:3000/users) — 200, matches schema
✖ POST /users (http://localhost:3000/users) — 201, 1 mismatch(es): body.email (required property missing)