---
name: generate_openapi_spec
description: "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:

```markdown
### {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**:
```json
{
  "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:

```markdown
| 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

```markdown
### {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

## 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.