ibanking-api-ai/.agents/skills/documentation-writer/SKILL.md

name, description, source

name	description	source
documentation-writer	Generate structured API documentation, OpenAPI annotations, and technical specifications from contracts and code.	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:

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

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