openapi-first
Generate API code, types, validators, mock servers, and client SDKs from a single OpenAPI 3.1 specification. Use whenever building or modifying an HTTP API endpoint. The OpenAPI doc is source of truth - drift between doc and code is a contract violation caught by tests. Triggers on requests involving REST endpoints, API design, or client/server contracts.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- openapi-first
- description
- Generate API code, types, validators, mock servers, and client SDKs from a single OpenAPI 3.1 specification. Use whenever building or modifying an HTTP API endpoint. The OpenAPI doc is source of truth - drift between doc and code is a contract violation caught by tests. Triggers on requests involving REST endpoints, API design, or client/server contracts.
02 资源文件 1
- 其他SKILL.md.bundle9.4 KB
03 SKILL.md 正文
OpenAPI First
The API contract is the source of truth. Code derives from it, not the other way around.
Tradeoff: Adds an upfront OpenAPI authoring step. Worth it: free types, free validators, free client SDKs, free mocks, and contract testing comes for free.
When to invoke
- New API endpoint requested
- Existing endpoint being modified (request/response shape changes)
- Client SDK needed for an existing API
- Migration from undocumented API to documented
Workflow
- Write or update the OpenAPI 3.1 spec at
openapi/<service>.yml. - Generate types for both server and client.
- Generate validators so runtime requests are checked against the schema.
- Implement the handler to satisfy the spec (the test is "the schema-validator passes against real requests/responses").
- Generate the mock server for frontend development.
- Add a contract test that exercises every operation against the spec.
Recommended tooling (TypeScript)
openapi-typescript— type generationzod-openapior@asteasolutions/zod-to-openapi— write schemas in Zod, derive OpenAPI from them@hono/zod-openapiorfastify-openapi-glue— server framework integrationorvalor@kubb/swagger-client— typed client SDK generation@stoplight/prism— mock serverschemathesisordredd— contract testing
For Python (FastAPI)
FastAPI generates OpenAPI from typed handlers — the spec is derived from code.
This works in reverse to "OpenAPI first." If you have an existing FastAPI app,
treat its /openapi.json output as authoritative and treat the docs export as
the canonical spec for client generation.
For Rust
utoipa— Rust code annotations generate OpenAPIpaperclip— alternative annotation-based generatorprogenitor— generate Rust client from OpenAPI
Quality gates
A change is done when all five hold:
- The OpenAPI spec validates against the OpenAPI 3.1 schema.
spectral lint openapi/<service>.ymlpasses with the default ruleset (extend with.spectral.yamlfor project rules).- Generated types are checked into the repo and re-generated by CI on schema changes. Drift = build failure.
- Contract tests run on every PR.
oasdiffdetects breaking changes, and a breaking change requires a major version bump.
Anti-patterns
Hand-writing types after the schema: defeats the purpose. Always generate.
Schema-after: writing the handler and then describing it in OpenAPI. Don't. The schema is the design artifact.
Optional everywhere: if a field is always required in practice, mark it required. Schema laxity becomes runtime errors.
Missing error responses: every operation should document 4xx and 5xx
responses with Problem Details (RFC 9457) bodies.
No versioning strategy: pick header-based (Accept: application/vnd.api+json; version=2) or path-based (/v2/) and stick to it.
Worked example
openapi/auth.yml:
openapi: 3.1.0
info:
title: Auth Service
version: 1.0.0
paths:
/auth/reset:
post:
operationId: requestPasswordReset
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ResetRequest'
responses:
'200':
description: Reset link sent
'422':
description: Invalid email
content:
application/problem+json:
schema: { $ref: '#/components/schemas/Problem' }
'429':
description: Rate limited
components:
schemas:
ResetRequest:
type: object
required: [email]
properties:
email: { type: string, format: email, maxLength: 320 }
Problem:
type: object
properties:
type: { type: string, format: uri }
title: { type: string }
status: { type: integer }
detail: { type: string }
Generated code provides:
- Server handler type signature
- Client SDK method
client.requestPasswordReset({ email }) - Mock server endpoint
- Contract test for valid + invalid inputs
This skill is working when: every API endpoint in the project is described
in OpenAPI, every type is generated (not hand-written), and contract tests run
on every PR. The intended record is
governance/telemetry/openapi-coverage.jsonl. Nothing writes it yet, so check by hand.
04 同仓库更多 Skills
karpathy-guidelines
Behavioral guidelines that reduce common LLM coding mistakes. Apply whenever writing, modifying, or reviewing code. Don't assume requirements, don't overcomplicate, don't refactor unrelated code, and define success criteria before implementing. Use this skill on every non-trivial coding task to avoid bloat, silent assumptions, and completion-bias.
unsigned-missing-sig-fixture
Test fixture (F.09) — SKILL.md without an accompanying .sig file. Default install rejects with exit 2; --allow-unsigned --rationale="..." proceeds.
unsigned-mismatched-sig-fixture
Test fixture (F.09) — SKILL.md whose accompanying .sig signs different content. NFR-F3 hash check catches this even with --allow-unsigned.
karpathy-guidelines
Behavioral guidelines that reduce common LLM coding mistakes. Apply whenever writing, modifying, or reviewing code. Don't assume requirements, don't overcomplicate, don't refactor unrelated code, and define success criteria before implementing. Use this skill on every non-trivial coding task to avoid bloat, silent assumptions, and completion-bias.
webhook-idempotency
Defend against double-processing of webhook events across every provider (Stripe, GitHub, Slack, Twilio, SendGrid). Idempotency-key pattern + replay-window enforcement + dedupe-storage strategy. Triggers on any webhook handler authoring (route matching /webhook(s)?/, Stripe-Signature / X-Hub-Signature-256 header references). Defense against OWASP ASI02 (Tool Misuse) -- a replayed webhook that re-triggers a destructive tool is the canonical control-flow-level replay attack. Universal across providers; stack-specific signature verification lives in stack-specific skills.
semgrep-scan
Run Semgrep static analysis to detect insecure code patterns - SQL injection, XSS, path traversal, weak crypto, broken auth, OWASP Top 10 issues. Use on every file change touching security-sensitive code and as part of the tiered security gate. Complements gitleaks (which catches secrets) by catching insecure logic.