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

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