just-vibeAPIs · apply by default
/api-openapi
Create or reconcile OpenAPI documentation with implementation
Use to maintain an OpenAPI contract; api-breaking assesses compatibility between versions, and client or SDK generation belongs to api-client.
Make it your own.
In Claude Code, use the slash command and add your context. In Codex, select api-openapi from the just-vibe skill picker, then send the same brief.
Version 0.11.0 also supports /jv api-openapi, /just-vibe api-openapi and /jv:api-openapi in Claude. See shortcut setup and context examples.
/just-vibe:api-openapi Reconcile the existing specification with actual request and error schemas./just-vibe:api-openapi Document nullable fields and a rate-limit response omitted from generated output./just-vibe:api-openapi Review supplied schema without running the provider; do not claim runtime conformance.What the agent does
- Identify the authoritative schema source, then compare its coverage with routes, serializers and route validators.
- Resolve documentation-versus-code discrepancies in the authoritative source.
- Validate references, required/null distinctions and representative examples.
Inputs
- existing OpenAPI/schema, implementation, and source-of-truth convention.
Optional context: scope, references, constraints, successCriteria, environment, mode, budget.
Scope
- Reads
- Reconcile documented paths, schemas, authentication, responses, and examples with actual intended behavior.
- Writes
- Apply: only the requested local changes and relevant isolated verification. Inspect/plan requests remain inspection/planning. External actions require their exact action and target in session authorization.
- Mode
- Apply; existing OpenAPI/schema, implementation, and source-of-truth convention.
- Prerequisites
- Interface definitions, producer/consumer source, authentication model, versioning constraints, and isolated test endpoints. External API calls must respect environment, credentials, rate limits, and side-effect scope.
Expected output
- Validated specification with covered routes and schema/example validation, and a list of remaining runtime discrepancies.
How the work is checked
- Examples conform to declared schemas; missing error responses are represented accurately.
When to stop or clarify
- Do not silently change runtime behavior to match stale documentation or overwrite generated files without updating their source.
Handling missing context
- Infer
- Read producer/consumer schemas, error contracts, auth conventions and known supported client versions.
- Assume
- Keep compatible response and pagination semantics where the brief does not request a breaking change.
- Ask
- Ask when contract sources disagree or an unknown consumer changes compatibility; do not require live credentials to write or test an isolated client.
Technical guidance
- Evidence
- Identify OpenAPI version, source-of-truth convention, generators, serializers and client usage.
- Method
- Reconcile path parameters, required/null semantics, security schemes and error responses; regenerate derived artifacts from their source.
- Pitfall
- OpenAPI 3.0 and 3.1 null/schema semantics differ; a valid schema can still document behavior the server never emits.
- Check
- Validate references/examples with the supported tooling and compare representative real requests/responses against the contract.
Situational decisions
When generated schema disagrees with runtime behavior: Correct the source of generation or document a deliberate contract change; do not patch generated output alone.
The coding agent follows this workflow using its available tools. Installation does not grant service access or guarantee an outcome. Read the compatibility notes.