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

```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](references/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 |
|------|---------