168 lines
5.0 KiB
Markdown
168 lines
5.0 KiB
Markdown
---
|
|
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]
|
|
```
|