/jaan-to:dev-api-contract
Generate OpenAPI 3.1 contracts from API resource entities.
Overview
Analyzes API resource entities and produces a validated OpenAPI 3.1 specification (api.yaml) with flat component schemas, RFC 9457 error responses, cursor-based pagination, named examples, and a companion markdown quick-start guide.
Usage
/jaan-to:dev-api-contract "User, Post, Comment"
/jaan-to:dev-api-contract "See PRD at jaan-to/outputs/pm/prd/01-user-auth/01-prd-user-auth.md"
/jaan-to:dev-api-contract "path/to/schema.sql"
| Argument | Required | Description |
|---|---|---|
| entities-or-prd-path | Yes | Comma-separated entity names, PRD path, database schema path, or existing OpenAPI spec path |
What It Asks
| Question | Why |
|---|---|
| Resources scope | Which entities to include in the contract |
| Versioning strategy | URL path /v1/, header, or no versioning |
| Authentication | OAuth2, API Key, JWT Bearer, or none |
| Depth | MVP (CRUD only), Production (full), or Framework (schemas only) |
| Pagination | Cursor-based, offset-based, or none |
| Consumers | Internal frontends, third-party devs, both, or M2M |
Questions are skipped when already answered by input or $JAAN_CONTEXT_DIR/tech.md.
What It Produces
Two files at $JAAN_OUTPUTS_DIR/dev/contract/{id}-{slug}/:
| File | Content |
|---|---|
api.yaml | OpenAPI 3.1 specification with all components and paths |
{id}-contract-{slug}.md | Quick-start guide with auth, examples, error handling, and tooling commands |
OpenAPI Spec Includes
| Section | Details |
|---|---|
| Schemas | Flat components/schemas with $ref — base (Timestamps, ProblemDetails, PaginationMeta) + per-resource (Create, Update, Response, List) |
| Errors | RFC 9457 Problem Details with ValidationProblemDetails extension for field-level errors |
| Pagination | Cursor-based with has_more + opaque cursor (or offset-based if selected) |
| Examples | Named media type examples per operation organized by scenario |
| Security | Configured security scheme applied globally |
Design Patterns
Based on research from 59-dev-api-contract.md (40+ sources):
- OpenAPI 3.1 with full JSON Schema 2020-12 alignment
- Flat component architecture — never deep inline, always
$ref - RFC 9457 error format with
application/problem+json - Null handling —
type: ["string", "null"](nevernullable: true) - Components-first generation — schemas before paths to minimize broken
$ref - GitHub REST API as 3.1 gold standard reference
Tech Stack Integration
Reads $JAAN_CONTEXT_DIR/tech.md to adapt the contract:
- Versioning from
#versioning— applies URL path, header, or date-based strategy - Auth patterns from
#patterns— configures security schemes - Frameworks from
#frameworks— addsx-frameworkextension - Constraints from
#constraints— informs validation rules
Workflow Chain
This skill fits in the dev workflow:
/jaan-to:dev-be-task-breakdown → /jaan-to:dev-api-contract → /jaan-to:dev-api-versioning
After generating the contract, the skill suggests:
- Mock server with Prism
- Client SDK generation with Orval
- Contract testing with Schemathesis
- Versioning plan with
/jaan-to:dev-api-versioning
Research Source
Based on comprehensive research at jaan-to/outputs/research/59-dev-api-contract.md covering schema design, RFC 9457 errors, example generation, versioning, AI generation guardrails, hybrid authoring, reference specs (GitHub, Stripe, Zalando), and the validation tooling stack (Spectral, Redocly, Prism, Schemathesis).