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

Common Status Codes

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:

Related Skills (Cross-Plugin)

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