api-contract-design
Design APIs using schema-first approach with OpenAPI/Swagger. Use when creating new APIs, documenting existing ones, or when frontend/backend teams need to work in parallel. Covers OpenAPI spec, validation, and code generation.
npx skills add majiayu000/claude-skill-registry --skill api-contract-design-doyajin174-myskills --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# API Contract Design OpenAPI(Swagger) 기반 스키마 우선 API 설계 스킬입니다. ## Core Principle > **"코드보다 계약(Contract)이 먼저다."** > **"프론트엔드와 백엔드가 동시에 개발할 수 있게 API를 먼저 정의한다."** ## Schema-First vs Code-First | 접근법 | 장점 | 단점 | |--------|------|------| | **Schema-First** (권장) | 병렬 개발 가능, 명확한 계약 | 초기 설계 시간 필요 | | Code-First | 빠른 시작 | 문서와 코드 불일치 위험 | ## OpenAPI 기본 구조 ### `openapi.yaml` ```yaml openapi: 3.1.0 info: title: My API version: 1.0.0 description: API for My Application servers: - url: https://api.example.com/v1 description: Production - url: http://localhost:3000/api description: Development paths: /users: get: summary: Get all users operationId: getUsers tags: - Users parameters: - name: page in: query schema: type: integer default: 1 - name: limit in: query schema: type: integer default: 20 maximum: 100 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/UserListResponse' '401': $ref: '#/components/responses/Unauthorized' post: summary: Create a new user operationId: createUser tags: - Users requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' responses: '201': description: U
- Core Principle
- Schema-First vs Code-First
- OpenAPI 기본 구조
- openapi.yaml
- 폴더 구조
- 분리된 스펙 (paths/users.yaml)
- 메인 스펙에서 참조
- TypeScript 타입 생성
- openapi-typescript
- 생성된 타입 사용
- API 클라이언트 생성
- openapi-fetch (권장)
- Orval (코드 생성)
- 요청 검증
npm install -D openapi-typescript npx openapi-typescript ./api/openapi.yaml -o ./src/types/api.ts npm install openapi-fetch npm install -D orval npm install swagger-ui-react npm install @scalar/nextjs-api-reference Prism (Stoplight) npm install -D @stoplight/prism-cli Mock 서버 실행 npx prism mock ./api/openapi.yaml
What does the api-contract-design skill do?
Design APIs using schema-first approach with OpenAPI/Swagger. Use when creating new APIs, documenting existing ones, or when frontend/backend teams need to work in parallel. Covers OpenAPI spec, validation, and code generation.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill api-contract-design-doyajin174-myskills --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.