leo-claude-mktplace/plugins/saas-api-platform/commands/api-validate.md

name, description, agent

name	description	agent
api validate	Validate routes against OpenAPI specification	api-validator

/api validate - OpenAPI Validation

Skills to Load

• skills/openapi-conventions.md
• skills/route-patterns.md
• skills/visual-header.md

Visual Output

Display header: API-PLATFORM - Validate

Usage

/api validate [--spec=<path>] [--strict]

Arguments:

• --spec: Path to OpenAPI spec file (default: auto-detect openapi.yaml or openapi.json)
• --strict: Treat warnings as errors

Prerequisites

Run /api setup first. Requires an existing OpenAPI specification to validate against.

Process

1. Locate OpenAPI Spec

Search for spec file in order:

1. Path provided via --spec flag
2. openapi.yaml in project root
3. openapi.json in project root
4. swagger.yaml or swagger.json in project root
5. docs/openapi.yaml or docs/openapi.json

If not found, report error and suggest /api docs to generate one.

2. Parse Route Definitions

Scan route files to extract implemented endpoints:

• HTTP method and path pattern
• Path parameters and query parameters
• Request body schema (if POST/PUT/PATCH)
• Response status codes and schemas
• Authentication requirements

3. Compare Against Spec

Run validation checks:

Check	Severity	Description
Missing endpoint in spec	FAIL	Route exists in code but not in OpenAPI spec
Missing endpoint in code	FAIL	Spec defines endpoint not implemented
Parameter mismatch	FAIL	Path/query parameters differ between code and spec
Schema mismatch	WARN	Request/response model fields differ from spec
Missing response codes	WARN	Code returns status codes not documented in spec
Missing descriptions	INFO	Endpoints or parameters lack descriptions
Missing examples	INFO	Spec lacks request/response examples
Deprecated endpoint still active	WARN	Spec marks endpoint deprecated but code still serves it

4. Generate Report

Group findings by severity and provide actionable fixes.

Output Format

+----------------------------------------------------------------------+
|  API-PLATFORM - Validate                                             |
+----------------------------------------------------------------------+

Spec: openapi.yaml (OpenAPI 3.0.3)
Routes Scanned: 14 endpoints in 4 files
Spec Endpoints: 16 defined

FINDINGS

FAIL (2)
  1. [POST /v1/orders] Missing from OpenAPI spec
     Fix: Add path definition to openapi.yaml

  2. [GET /v1/users] Query param 'role' not in spec
     Fix: Add 'role' query parameter to path definition

WARN (3)
  1. [PUT /v1/products/{id}] Response 422 not documented
     Fix: Add 422 response to spec with validation error schema

  2. [GET /v1/orders] Schema mismatch - 'total_amount' field
     Code: float, Spec: string
     Fix: Update spec to use number type

  3. [DELETE /v1/users/{id}] Marked deprecated in spec
     Suggestion: Remove endpoint or update spec status

INFO (1)
  1. [GET /v1/products] Missing response example
     Suggestion: Add example to improve documentation

SUMMARY
  Endpoints:  14 implemented / 16 in spec
  Coverage:   87.5%
  FAIL:       2 (must fix)
  WARN:       3 (should fix)
  INFO:       1 (improve)

VERDICT: FAIL (2 blocking issues)

Exit Guidance

• FAIL findings: Block deployment, spec and code must agree
• WARN findings: Fix before release for accurate documentation
• INFO findings: Improve for developer experience
• --strict mode: All WARN become FAIL