openapi-contract-authoringlisted
Install: claude install-skill mcorbett51090/RavenClaude
# OpenAPI Contract Authoring
## When to Use This Skill
Invoke before writing any server code. The OpenAPI document is the source of truth; code follows the spec, never the reverse.
## 1. Document Skeleton (OpenAPI 3.1)
```yaml
openapi: "3.1.0"
info:
title: Orders API
version: "1.0.0"
description: |
Manages customer orders. Breaking changes bump the major version.
contact:
email: api-team@example.com
servers:
- url: https://api.example.com/v1
description: Production
- url: https://api-staging.example.com/v1
description: Staging
paths: {}
components:
schemas: {}
responses: {}
parameters: {}
securitySchemes: {}
security:
- BearerAuth: []
```
## 2. Resource Modeling Checklist
| Decision | Rule |
|---|---|
| URL shape | Plural nouns: `/orders`, `/orders/{orderId}/items` |
| Verb in URL | Never. `POST /orders/{id}/cancel` → `POST /orders/{id}/cancellations` |
| ID type | `string` (UUID) — never expose sequential integers |
| Collections | Always paginated; never return an unbounded array at the root |
| Nested depth | Cap at two levels (`/parent/{id}/child`) — deeper → join via query |
## 3. Path Item Template
```yaml
/orders/{orderId}:
parameters:
- $ref: "#/components/parameters/OrderId"
get:
operationId: getOrder
summary: Retrieve an order by ID
tags: [orders]
responses:
"200":
description: Order found
content:
application/json:
schema:
$ref: "#/compone