api-contract-design
Design Type-Safe APIs with OpenAPI Schema-First Approach
Frontend and backend teams often face integration issues when APIs are poorly defined or change frequently. This skill enables collaborative API design using OpenAPI specifications, generating TypeScript types and clients automatically for type-safe development across your entire stack.
์คํฌ ZIP ๋ค์ด๋ก๋
Claude์์ ์ ๋ก๋
์ค์ โ ๊ธฐ๋ฅ โ ์คํฌ โ ์คํฌ ์ ๋ก๋๋ก ์ด๋
ํ ๊ธ์ ์ผ๊ณ ์ฌ์ฉ ์์
ํ ์คํธํด ๋ณด๊ธฐ
"api-contract-design" ์ฌ์ฉ ์ค์ ๋๋ค. Create an OpenAPI specification for user authentication with JWT tokens
์์ ๊ฒฐ๊ณผ:
- OpenAPI 3.1 specification with /auth/login, /auth/register, /auth/refresh, and /auth/logout endpoints
- TypeScript types for LoginRequest, LoginResponse, UserProfile, and JWTPayload
- Type-safe API client code with proper error handling and token management
- Zod validation schemas for request body validation
"api-contract-design" ์ฌ์ฉ ์ค์ ๋๋ค. Design an OpenAPI spec for a blog API with posts, comments, and tags
์์ ๊ฒฐ๊ณผ:
- Complete paths definition for CRUD operations on posts, comments, and tags
- Schema definitions with relationships between posts, authors, comments, and tags
- Pagination and filtering parameters for list endpoints
- Error response schemas for 400, 401, 403, and 404 scenarios
๋ณด์ ๊ฐ์ฌ
์์ This is a documentation-only skill containing educational content about API contract design. All static findings are false positives triggered by code examples in documentation. No executable code, network calls, file access, or external commands exist in this skill.
์ํ ์์ธ
โ๏ธ ์ธ๋ถ ๋ช ๋ น์ด (45)
๐ ๋คํธ์ํฌ ์ ๊ทผ (10)
๐ ํ์ผ ์์คํ ์ก์ธ์ค (3)
๐ ํ๊ฒฝ ๋ณ์ (2)
ํ์ง ์ ์
๋ง๋ค ์ ์๋ ๊ฒ
Build APIs with Parallel Development
Design API contracts first to enable frontend and backend teams to work in parallel with type safety.
Document Legacy REST APIs
Create OpenAPI specifications for existing APIs to add documentation and generate type-safe clients.
Establish Organization-Wide API Standards
Define consistent patterns, versioning strategies, and documentation standards across all services.
์ด ํ๋กฌํํธ๋ฅผ ์ฌ์ฉํด ๋ณด์ธ์
Create an OpenAPI 3.1 specification for a todo API with CRUD operations. Include endpoints for creating todos with title and description, listing todos with pagination, updating todo status, and deleting todos. Define proper 400 and 404 error responses.
Design an OpenAPI specification for an e-commerce product API with filtering by category and price range, cursor-based pagination, search with fuzzy matching, image upload endpoints, and bulk operations. Include OAuth2 security and rate limiting headers.
Create an OpenAPI 3.1 spec for a chat API with REST endpoints for user and room management, message threading, file attachments, read receipts, and typing indicators. Include WebSocket event documentation and HMAC webhook verification.
Design a comprehensive multi-tenant SaaS API with tenant isolation via headers, 50+ RBAC permissions, webhook subscriptions with HMAC verification, GraphQL gateway integration, content negotiation versioning, request transformation middleware, and polymorphic response patterns using discriminator.
๋ชจ๋ฒ ์ฌ๋ก
- Use descriptive operationId values that clearly indicate the action such as createUser or getUserById
- Organize large specifications by splitting paths and schemas into separate files with clear naming conventions
- Include comprehensive examples in your schemas to help consumers understand expected data formats and improve documentation
ํผํ๊ธฐ
- Avoid mixing schema-first and code-first approaches within the same project as it leads to inconsistencies
- Do not skip the team review process since API contracts should be agreed upon before implementation begins
- Never expose sensitive data like passwords or API keys in your OpenAPI examples or documentation
์์ฃผ ๋ฌป๋ ์ง๋ฌธ
Which OpenAPI version should I use?
How do I handle API versioning?
Can I integrate this with React Query?
Is my API specification data safe?
What if generated types do not match my backend?
How does this compare to GraphQL?
๊ฐ๋ฐ์ ์ธ๋ถ ์ ๋ณด
ํ์ผ ๊ตฌ์กฐ
๐ marketplace.json
๐ SKILL.md