openapi-design
Contract-first REST API design with OpenAPI 3.1 specification
When & Why to Use This Skill
This Claude skill facilitates professional-grade, contract-first REST API design using the OpenAPI 3.1 specification. It enables developers to architect robust API contracts, define reusable schemas, and establish clear communication between frontend and backend teams before implementation begins, ensuring high-quality documentation and standardized development workflows.
Use Cases
- Design-First Development: Creating comprehensive OpenAPI 3.1 specifications to serve as a single source of truth for frontend and backend teams.
- API Architecture & Schema Modeling: Defining complex data structures, reusable components, and security schemes to ensure consistency across microservices.
- Standardization & Best Practices: Enforcing industry-standard naming conventions, HTTP status codes, and versioning strategies for RESTful services.
- Documentation-First Workflow: Leveraging MCP tools to research design patterns and verify syntax against the latest OpenAPI standards before generating implementation code.
| name | openapi-design |
|---|---|
| description | Contract-first REST API design with OpenAPI 3.1 specification |
| allowed-tools | Read, Glob, Grep, Write, Edit, mcp__perplexity__search, mcp__context7__resolve-library-id, mcp__context7__query-docs |
OpenAPI Design Skill
When to Use This Skill
Use this skill when:
- Designing REST APIs - OpenAPI 3.1 for contract-first API design
- Defining API contracts - Schemas, paths, parameters, responses
- API best practices - Naming conventions, status codes, versioning
MANDATORY: Documentation-First Approach
Before creating OpenAPI specifications:
- Invoke
docs-managementskill for API design patterns - Verify OpenAPI 3.1 syntax via MCP servers (context7 for latest spec)
- Base all guidance on OpenAPI 3.1 specification
Contract-First Approach
Why Contract-First?
- Design before implementation: Think through API before coding
- Parallel development: Frontend and backend can work simultaneously
- Clear contract: Unambiguous specification for all parties
- Auto-generation: Generate clients, servers, documentation
- Validation: Validate requests/responses against schema
Workflow
Requirements → OpenAPI Spec → Review → Generate → Implement → Test
↑ ↓
←←←←←←←←←←←←← Iterate as needed ←←←←←←←←←←←←←←←←←←←←←←
OpenAPI 3.1 Structure Overview
openapi: 3.1.0
info:
title: API Title
version: 1.0.0
description: API description
servers:
- url: https://api.example.com/v1
description: Production
tags:
- name: Orders
description: Order management
paths:
# Define endpoints - see paths-definition.md
components:
schemas: { }
securitySchemes: { }
responses: { }
parameters: { }
For complete template: See paths-definition.md
Quick Reference
HTTP Methods
| Method | Purpose | Idempotent |
|---|---|---|
| GET | Retrieve resource(s) | Yes |
| POST | Create resource | No |
| PUT | Replace resource | Yes |
| PATCH | Partial update | No |
| DELETE | Remove resource | Yes |
Common Status Codes
| Code | Use For |
|---|---|
| 200 | Successful GET, PUT, PATCH |
| 201 | Resource created (POST) |
| 204 | Successful DELETE |
| 400 | Malformed request |
| 401 | Authentication required |
| 404 | Resource not found |
| 422 | Validation error |
For complete guidance: See design-best-practices.md
Design Workflow
- Understand requirements: What operations are needed?
- Design resources: Identify entities and relationships
- Define schemas: Create reusable component schemas
- Specify endpoints: Define paths and operations
- Add security: Configure authentication/authorization
- Document examples: Add request/response examples
- Validate: Use linting tools (Spectral, etc.)
- Review: Get team feedback before implementation
References
Load on-demand based on need:
| Reference | Load When |
|---|---|
| paths-definition.md | Defining REST endpoints, operations, parameters |
| components-definition.md | Creating schemas, responses, security schemes |
| design-best-practices.md | Reviewing naming, status codes, versioning |
Related Skills (Cross-Plugin)
| Phase | Skill | Plugin | Purpose |
|---|---|---|---|
| DESIGN | openapi-design (this skill) |
formal-specification | Architecture research, pattern selection |
| AUTHORING | openapi-authoring |
spec-driven-development | Concrete YAML file creation |
| GOVERNANCE | contract-first-design |
spec-driven-development | API governance, code generation |
Workflow: Design (research patterns) → Author (create YAML) → Govern (enforce contracts)
External References
- OpenAPI 3.1 Specification - Official specification
- RFC 7231 - HTTP Semantics - HTTP methods and status codes
- RFC 7807 - Problem Details - Standard error response format
- Spectral - OpenAPI linting tool
MCP Research
For current OpenAPI patterns and tools:
perplexity: "OpenAPI 3.1 specification" "REST API design patterns"
context7: "openapi" (for official documentation)
ref: "OpenAPI spec examples" "JSON Schema patterns"
Version History
- v2.0.0 (2026-01-17): Refactored to progressive disclosure pattern
- Extracted 3 reference files (~500 lines)
- Hub reduced from 698 to ~130 lines
- v1.0.0 (2025-12-26): Initial release
Last Updated: 2026-01-17