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