openapi-design

Original：🇺🇸 English

Translated

Contract-first REST API design with OpenAPI 3.1 specification

1installs

Sourcemelodic-software/claude-code-plugins

Added on2026-02-17

NPX Install

npx skill4agent add melodic-software/claude-code-plugins openapi-design

SKILL.md Content

View Translation Comparison →

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

text

Requirements → OpenAPI Spec → Review → Generate → Implement → Test
     ↑                                                      ↓
     ←←←←←←←←←←←←← Iterate as needed ←←←←←←←←←←←←←←←←←←←←←←

OpenAPI 3.1 Structure Overview

yaml

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: