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