Agent skill · software engineering · aiskillstore
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.
Why this skill is useful
Provides detailed OpenAPI schema examples and validation patterns that the AI wouldn't reliably generate on its own.
What it needs
About 4k tokens when loaded. Last updated 2026-08-07. 405 stars on the source repository.
What this skill does
API Contract Design OpenAPI(Swagger) 기반 스키마 우선 API 설계 스킬입니다. Core Principle "코드보다 계약(Contract)이 먼저다." "프론트엔드와 백엔드가 동시에 개발할 수 있게 API를 먼저 정의한다." Schema-First vs Code-First 접근법 장점 단점 -------- ------ ------ Schema-First (권장) 병렬 개발 가능, 명확한 계약 초기 설계 시간 필요 Code-First 빠른 시작 문서와 코드 불일치 위험 OpenAPI 기본 구조 openapi.yaml 폴더 구조 분리된 스펙 (paths/users.yaml) 메인 스펙에서 참조 TypeScript 타입 생성 openapi-typescript 생성된 타입 사용 API 클라이언트 생성 openapi-fetch (권장) Orval (코드 생성) 요청 검증 Zod + OpenAPI API 문서 UI Swagger UI Scalar (모던 대안) 버전 관리 URL 버전 관리 헤더 버전 관리 Workflow Schema-First 개발 흐름 Mock 서버 Checklist 스펙 작성 [ ] 모든 엔드포인트 정의 [ ] Request/Response 스키마 정의 [ ] 에러 응답 정의 [ ] 인증 방식 정의 [ ] 예제 데이터 포함 타입 안전성 [ ] TypeScript 타입 생성 [ ] 요청 검증 (Zod) [ ] 응답 타입 체크 문서화 [ ] API 문서 UI 제공 [ ] 변경 이력 관리 [ ] 버전 관리 전략 References OpenAPI Specification openapi-typescript openapi-fetch Prism Mock Server
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aiskillstore/api-contract-design