opencode-workflow/skills/generate_openapi_spec/SKILL.md

name	description
generate_openapi_spec	Produce OpenAPI or gRPC API contract definitions including endpoints, request/response schemas, error codes, idempotency, pagination, and filtering. A deliverable skill referenced by design-architecture.

This skill provides guidance and format requirements for producing API contract definitions within the architecture document.

This is a deliverable skill, not a workflow skill. It is referenced by design-architecture when producing API contract artifacts.

Purpose

The Architect must produce API contract definitions that are specific enough for implementation. API contracts define the interface between services and between clients and the system.

REST API (OpenAPI Style)

For REST APIs, use OpenAPI-style definitions within the architecture document.

Endpoint Definition Format

Each endpoint must include:

### {METHOD} {path}

**Description**: {What this endpoint does}

**Authentication**: {None / Bearer Token / API Key / mTLS}

**Idempotency**: {None / Idempotent by method / Requires Idempotency-Key header}

**Request**:

| Field | Location | Type | Required | Description |
|-------|----------|------|----------|-------------|
| ... | header / path / query / body | ... | yes/no | ... |

**Request Body** (if applicable):
```json
{
  "field1": "type",
  "field2": "type"
}

Response (Success):

Status Code	Description	Response Schema
200 / 201	...	...

Response Body:

{
  "field1": "type",
  "field2": "type"
}

Error Responses:

Status Code	Error Code	Description	When
400	INVALID_INPUT	...	...
401	UNAUTHORIZED	...	...
404	NOT_FOUND	...	...
409	CONFLICT	...	...
429	RATE_LIMITED	...	...
500	INTERNAL_ERROR	...	...

Pagination (if applicable):

• Default page size: {n}
• Maximum page size: {n}
• Pagination parameters: offset / cursor
• Response includes: total_count, has_more

Filtering (if applicable):

• Supported filters: {list of filterable fields}
• Filter operators: eq, ne, gt, lt, in, contains

### Error Response Format

Define a consistent error response format:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": [
      {
        "field": "field_name",
        "message": "Specific error message"
      }
    ],
    "request_id": "uuid"
  }
}

Error Code Catalog

Define system-wide error codes:

| Code | HTTP Status | Description |
|------|-------------|-------------|
| INVALID_INPUT | 400 | Request validation failed |
| UNAUTHORIZED | 401 | Authentication required |
| FORBIDDEN | 403 | Insufficient permissions |
| NOT_FOUND | 404 | Resource not found |
| CONFLICT | 409 | Resource already exists |
| RATE_LIMITED | 429 | Too many requests |
| INTERNAL_ERROR | 500 | Unexpected server error |
| SERVICE_UNAVAILABLE | 503 | Dependent service unavailable |

gRPC API

For gRPC APIs, define the service and method specifications.

Service Definition Format

### {ServiceName}

**Package**: {package.name}

#### {MethodName}

**Request**: {MessageName}

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| ... | ... | ... | ... |

**Response**: {MessageName}

| Field | Type | Description |
|-------|------|-------------|
| ... | ... | ... |

**Error Codes**:

| Code | Description |
|------|-------------|
| INVALID_ARGUMENT | ... |
| NOT_FOUND | ... |
| ... | ... |

**Idempotency**: {None / Idempotent / Requires request_id}

Required API Contract Elements

Endpoints

• Every functional requirement from the PRD must have at least one API endpoint
• Each endpoint must map to the PRD functional requirement it satisfies

Request / Response Schemas

• Every field must have type, required/optional, and description
• Nested objects must be fully defined
• Enum values must be listed

Error Codes

• Define consistent error codes across the system
• Differentiate client errors (4xx) from server errors (5xx) from business rule violations
• Include error response format

Idempotency

• Identify which endpoints require idempotency
• Define idempotency mechanism (method-based, key-based)
• Define idempotency key format and TTL

Pagination

• Define pagination mechanism for all list endpoints
• Specify default and maximum page sizes
• Define pagination response format

Filtering

• Define supported filter fields for list endpoints
• Define filter operators
• Define sort options

Rate Limiting (when applicable)

• Define rate limit expectations per endpoint
• Define rate limit headers and response format

Knowledge Contract Reference

This deliverable skill works alongside the api-contract-design knowledge contract:

• api-contract-design provides the theoretical guidance on API design principles
• This skill provides the concrete output format and completeness requirements

Anti-Placeholder Rule

Examples in this skill are illustrative only. Do not reuse placeholder endpoints, field names, response schemas, or error codes unless explicitly required by the PRD. Every endpoint, field, status code, and error code must be grounded in actual requirements and match the architecture document's functional requirements.

Embedding in Architecture Document

All API contract definitions must be embedded within the ## API Contract section of docs/architecture/{feature}.md.

Do NOT produce separate OpenAPI YAML or gRPC proto files. All API contracts must be within the single architecture document.