---
name: documentation-writer
description: Generate structured API documentation, OpenAPI annotations, and technical specifications from contracts and code.
source: community + V4 patterns (pinned 2026-03-19)
---

# Documentation Writer

## Overview
Generate structured documentation from API contracts, code, and specifications. Focuses on OpenAPI annotations, technical specs, and developer-facing documentation.

## When to Use
- Writing OpenAPI/Swagger annotations for JAX-RS Resources
- Generating API specification documents from contracts
- Creating developer onboarding documentation
- Producing technical decision records (ADRs)
- Enriching `@APIResponse` annotations with real examples

## Instructions

### 1. Gather Context
Before generating documentation:
- Read the API contract (headers, body, response structure)
- Read the error catalog (`messages.content` in `application.yml`)
- Check the reference implementation for actual response shapes
- Identify all possible HTTP status codes

### 2. Generate OpenAPI Annotations

For each endpoint, produce complete `@Operation` and `@APIResponse` annotations:

```java
@Operation(
    summary = "Evaluate customer behavior against blacklist",
    description = "Validates customer restrictions (L1) against the domain blacklist service"
)
@APIResponse(
    responseCode = "200",
    description = "Successful evaluation",
    content = @Content(
        mediaType = "application/json",
        schema = @Schema(implementation = RecCustomerBehaviorResponse.class),
        examples = @ExampleObject(
            name = "Successful evaluation",
            value = """
            {
              "statusResponse": {
                "status": "ok",
                "statusCode": "200",
                "message": "Operacion exitosa",
                "traceId": "SESSION-ABC-123"
              }
            }
            """
        )
    )
)
@APIResponse(
    responseCode = "400",
    description = "Validation error - required field missing",
    content = @Content(
        schema = @Schema(implementation = ApiResponse.class),
        examples = @ExampleObject(
            name = "Missing required field",
            value = """
            {
              "statusResponse": {
                "status": "error",
                "statusCode": "VDE01",
                "message": "Error en dato de entrada obligatorio: customerReference",
                "traceId": "SESSION-ABC-123"
              }
            }
            """
        )
    )
)
@APIResponse(
    responseCode = "409",
    description = "Backend internal error",
    content = @Content(
        schema = @Schema(implementation = ApiResponse.class),
        examples = @ExampleObject(
            name = "Backend conflict",
            value = """
            {
              "statusResponse": {
                "status": "error",
                "statusCode": "PIB-00",
                "message": "Error Interno backend",
                "traceId": "SESSION-ABC-123"
              }
            }
            """
        )
    )
)
@APIResponse(
    responseCode = "503",
    description = "Service unavailable - maintenance window",
    content = @Content(
        schema = @Schema(implementation = ApiResponse.class),
        examples = @ExampleObject(
            name = "Service in maintenance",
            value = """
            {
              "statusResponse": {
                "status": "error",
                "statusCode": "VRN04",
                "message": "Servicio en horario de mantenimiento",
                "traceId": "SESSION-ABC-123"
              }
            }
            """
        )
    )
)
```

### 3. Map Error Codes to Annotations

Use the error catalog from `application.yml` → `messages.content`:

| Error Code | HTTP | `@APIResponse(responseCode=)` | Example message |
|---|---|---|---|
| `200` | 200 | `"200"` | `"Operacion exitosa"` |
| `VDE01` | 400 | `"400"` | `"Error en dato de entrada obligatorio: %s"` |
| `VDE02` | 400 | `"400"` | `"Error en valor permitido para campo: %s"` |
| `VRN04` | 503 | `"503"` | `"Servicio en horario de mantenimiento"` |
| `PIB-00` | 409 | `"409"` | `"Error Interno backend"` |

### 4. Documentation Quality Checklist

- [ ] Every endpoint has `@Operation(summary, description)`
- [ ] Every possible HTTP status has an `@APIResponse`
- [ ] Every `@APIResponse` includes `@ExampleObject` with realistic data
- [ ] Error examples show `status: "error"` + `traceId` consistently
- [ ] Header parameters have `@Parameter(description, required)`
- [ ] Request body schema matches the actual DTO
- [ ] `@Schema` descriptions are in business language, not technical jargon

## Output Format

When generating spec documents, use this structure:

```markdown
# API Specification — <API Name>

## Endpoint
| Method | Path | Description |
|---|---|---|

## Headers
| Name | Required | Description |

## Request Body
| Field | Type | Required | Validation | Error Code |

## Response (Success)
[JSON example]

## Response (Errors)
[Table + JSON examples per error code]

## Downstream Services
[Table of config keys, URLs, methods]
```