Tools reference

list_endpoints, get_endpoint, lint_spec, diff_specs и contract_test: входные данные, результат и примеры ответов.

list_endpoints

Перечисляет все эндпоинты каталога (метод, путь и summary), без подробностей по запросу и ответам. Пригодится, чтобы понять, что вообще есть, прежде чем звать get_endpoint.

Необязательный параметр filter: поиск подстроки без учёта регистра по пути, summary и тегам.

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

get_endpoint

Возвращает по одному эндпоинту полный текст в формате Copy for AI (Purpose, Request, Parameters, Validation, Success Response и Error Responses), принимая его method и path.

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, отсутствие тегов, отсутствие ответов 4xx и 5xx, неописанные ответы и повторяющиеся идентификаторы операций.

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

diff_specs

Сравнивает загруженный каталог с другой спецификацией (её задают через path для локального файла или url) и показывает добавленные и удалённые эндпоинты, а также ломающие и информационные изменения полей: новые обязательные параметры, ставшее обязательным тело запроса, убранный код ответа.

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)