chowbea-axios - Type-safe Axios Client Generator

The validate command analyzes your OpenAPI specification and reports issues that could cause problems during type generation.

Usage

chowbea-axios validate [flags]

What It Checks

Validation is grouped into seven categories. Each issue carries a severity (error, warning, or info) and a JSON Pointer to where it was found.

Category	What it covers
`structure`	Top-level required fields — `openapi`/`swagger` version, `info`, `paths`.
`operations`	Every operation has an `operationId` and at least one response.
`references`	Every `$ref` resolves; no circular chains beyond the configured depth.
`parameters`	Path parameters declared in URLs are also declared in the operation. Query/header params are well-formed.
`responses`	Response definitions are present and reference resolvable schemas.
`type-quality`	Heuristics that affect generation quality — missing types, untyped `any`, `additionalProperties: true` patterns.
`schemas`	Component schemas are well-formed and referenced.

Flags

Flag	Short	Description	Default
`--config`	`-c`	Path to api.config.toml	Auto-detected
`--spec`	`-s`	Path to OpenAPI spec file	From cache
`--strict`	-	Treat warnings as errors	`false`
`--quiet`	`-q`	Suppress non-error output	`false`
`--verbose`	`-v`	Show detailed output	`false`

Examples

Validate Cached Spec

chowbea-axios validate

Validate Specific File

chowbea-axios validate --spec ./openapi.json

Strict Mode

# Fail on warnings too
chowbea-axios validate --strict

Output

No Issues

╭────────────────────────────────────────
│ chowbea-axios validate
├────────────────────────────────────────
│
│ ✓ Validating OpenAPI spec... (specPath=app/services/api/_internal/openapi.json)
│
╰────────────────────────────────────────
│
│ ✓ Validation complete (errors=0, warnings=0)
│ ✓ OpenAPI spec is valid

With Warnings

╭────────────────────────────────────────
│ chowbea-axios validate
├────────────────────────────────────────
│
│ ✓ Validating OpenAPI spec...
│
├────────────────────────────────────────
│ Warnings
├────────────────────────────────────────
│
│ ⚠ Missing operationId - operation will be skipped during generation (path=/paths/users/get)
│ ⚠ Missing operationId - operation will be skipped during generation (path=/paths/users/post)
│
╰────────────────────────────────────────
│
│ ✓ Validation complete (errors=0, warnings=2)
│ ✓ OpenAPI spec is valid

With Errors

╭────────────────────────────────────────
│ Errors
├────────────────────────────────────────
│
│ ✗ Missing 'openapi' or 'swagger' version field (path=/)
│ ✗ Missing required 'info' object (path=/info)
│
╰────────────────────────────────────────
│
│ ✓ Validation complete (errors=2, warnings=0)

Severity Levels

Severity	When	Behavior
`error`	The spec is malformed enough that generation will fail or silently drop endpoints	Non-zero exit; always reported.
`warning`	Generation will succeed but quality will suffer (missing `operationId`, untyped responses)	Reported; exits non-zero only under `--strict`.
`info`	Stylistic or low-impact notes	Reported; never fails.

Each category shows a passed / failed / total checks count so you can see at a glance which areas are clean and which need work.

Why operationId Matters

Operations without operationId will:

Not generate operation-based methods (api.op.xxx)
Still work with path-based API (api.get("/path"))

Example spec without operationId:

paths:
  /users:
    get:
      # No operationId - will be skipped for operations
      summary: List users

With operationId:

paths:
  /users:
    get:
      operationId: listUsers  # Will generate api.op.listUsers()
      summary: List users

Use Cases

Before Deployment

# Ensure spec is valid before CI/CD
chowbea-axios validate --strict

Debugging Missing Operations

# See which endpoints lack operationId
chowbea-axios validate

Validating External Specs

# Check a spec before using it
chowbea-axios validate --spec ./external-api.json

Exit Codes

Code	Meaning
0	Valid (no errors, warnings allowed)
1	Errors found, or warnings found with --strict

validate