OpenAPI Design Skill Skill

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-management skill 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

Agent Skills: OpenAPI Design Skill

Install this agent skill to your local

Skill Files