AI Prompt: Forma3D.Connect — Phase 5v: OpenAPI Response Examples¶

Purpose: This prompt instructs an AI to add response examples to Swagger/OpenAPI documentation
Estimated Effort: 3-4 hours
Prerequisites: Phase 5u completed (File Naming)
Output: Complete OpenAPI documentation with response examples
Status: 🟡 PENDING

🎯 Mission¶

You are implementing Phase 5v: OpenAPI Response Examples — addressing TD-020 (Missing OpenAPI Response Examples) from the technical debt register.

Why This Matters:

Missing response examples makes API exploration harder:

1. Poor DX: Developers can't see expected response shapes
2. Integration Friction: Frontend devs must guess response format
3. Testing Gaps: No clear contract for response validation
4. Documentation Incomplete: Swagger UI less useful

📋 Context: Technical Debt Item¶

TD-020: Missing OpenAPI Response Examples¶

🛠️ Implementation¶

Phase 1: Add Response Decorators (2 hours)¶

Update controllers with @ApiResponse examples:

import { ApiResponse, ApiOkResponse } from '@nestjs/swagger';

@Controller('api/v1/orders')
export class OrdersController {
  @Get()
  @ApiOkResponse({
    description: 'List of orders',
    schema: {
      example: {
        data: [
          {
            id: 'order-123',
            shopifyOrderId: '5123456789',
            status: 'PROCESSING',
            customerName: 'John Doe',
            totalPrice: '99.99',
            createdAt: '2026-01-15T10:30:00Z',
          },
        ],
        pagination: {
          page: 1,
          pageSize: 20,
          total: 150,
        },
      },
    },
  })
  findAll() {}

  @Get(':id')
  @ApiOkResponse({
    description: 'Order details',
    type: OrderDto,
  })
  @ApiResponse({
    status: 404,
    description: 'Order not found',
    schema: {
      example: {
        statusCode: 404,
        message: 'Order not found: order-123',
        error: 'Not Found',
      },
    },
  })
  findOne() {}
}

Phase 2: Add DTO Examples (1 hour)¶

Use @ApiProperty with examples:

export class OrderDto {
  @ApiProperty({ example: 'order-123' })
  id: string;

  @ApiProperty({ example: '5123456789' })
  shopifyOrderId: string;

  @ApiProperty({ example: 'PROCESSING', enum: OrderStatus })
  status: OrderStatus;

  @ApiProperty({ example: '2026-01-15T10:30:00Z' })
  createdAt: Date;
}

Phase 3: Add Error Response Examples (1 hour)¶

Create standard error response schemas.

✅ Validation Checklist¶

• All endpoints have response examples
• DTOs have @ApiProperty examples
• Error responses documented
• Swagger UI shows examples
• pnpm nx build api passes

END OF PROMPT

This prompt resolves TD-020 from the technical debt register.