melodic-software/openapi-design

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:

1. Invoke docs-management skill for API design patterns
2. Verify OpenAPI 3.1 syntax via MCP servers (context7 for latest spec)
3. Base all guidance on OpenAPI 3.1 specification

Contract-First Approach

Why Contract-First?

1. Design before implementation: Think through API before coding
2. Parallel development: Frontend and backend can work simultaneously
3. Clear contract: Unambiguous specification for all parties
4. Auto-generation: Generate clients, servers, documentation
5. 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

1. Understand requirements: What operations are needed?
2. Design resources: Identify entities and relationships
3. Define schemas: Create reusable component schemas
4. Specify endpoints: Define paths and operations
5. Add security: Configure authentication/authorization
6. Document examples: Add request/response examples
7. Validate: Use linting tools (Spectral, etc.)
8. 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