digiqagent 1.2.0

package/skills/swagger-generator/openapi-patterns.md

@@ -0,0 +1,667 @@
+# OpenAPI Reusable Patterns
+
+Reference patterns for common API constructs. Copy and adapt these into generated specs.
+
+## Standard Error Response Schema
+
+```yaml
+components:
+  schemas:
+    ErrorResponse:
+      type: object
+      required:
+        - statusCode
+        - message
+        - error
+      properties:
+        statusCode:
+          type: integer
+          example: 400
+        message:
+          oneOf:
+            - type: string
+            - type: array
+              items:
+                type: string
+          example: "Validation failed"
+        error:
+          type: string
+          example: "Bad Request"
+        timestamp:
+          type: string
+          format: date-time
+          example: "2025-01-15T10:30:00Z"
+        path:
+          type: string
+          example: "/api/users"
+
+  responses:
+    BadRequest:
+      description: Invalid request parameters or body
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            statusCode: 400
+            message: ["email must be a valid email", "name must not be empty"]
+            error: "Bad Request"
+
+    Unauthorized:
+      description: Missing or invalid authentication token
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            statusCode: 401
+            message: "Invalid or expired token"
+            error: "Unauthorized"
+
+    Forbidden:
+      description: Insufficient permissions for this operation
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            statusCode: 403
+            message: "You do not have permission to access this resource"
+            error: "Forbidden"
+
+    NotFound:
+      description: Requested resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            statusCode: 404
+            message: "Resource with id '123' not found"
+            error: "Not Found"
+
+    Conflict:
+      description: Resource already exists or state conflict
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            statusCode: 409
+            message: "A user with this email already exists"
+            error: "Conflict"
+
+    UnprocessableEntity:
+      description: Request understood but semantically invalid
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            statusCode: 422
+            message: "Cannot assign task to a deactivated user"
+            error: "Unprocessable Entity"
+
+    InternalError:
+      description: Unexpected server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            statusCode: 500
+            message: "An unexpected error occurred"
+            error: "Internal Server Error"
+```
+
+## Pagination — Offset/Limit
+
+```yaml
+# Query parameters for list endpoints
+parameters:
+  PageParam:
+    name: page
+    in: query
+    description: Page number (1-based)
+    schema:
+      type: integer
+      minimum: 1
+      default: 1
+
+  LimitParam:
+    name: limit
+    in: query
+    description: Number of items per page
+    schema:
+      type: integer
+      minimum: 1
+      maximum: 100
+      default: 20
+
+  SortByParam:
+    name: sortBy
+    in: query
+    description: Field to sort by
+    schema:
+      type: string
+      default: createdAt
+
+  SortOrderParam:
+    name: sortOrder
+    in: query
+    description: Sort direction
+    schema:
+      type: string
+      enum: [asc, desc]
+      default: desc
+
+# Wrap list responses with pagination metadata
+schemas:
+  PaginationMeta:
+    type: object
+    properties:
+      page:
+        type: integer
+        example: 1
+      limit:
+        type: integer
+        example: 20
+      totalItems:
+        type: integer
+        example: 150
+      totalPages:
+        type: integer
+        example: 8
+      hasNextPage:
+        type: boolean
+        example: true
+      hasPreviousPage:
+        type: boolean
+        example: false
+
+  # Usage: compose with resource list
+  PaginatedUserList:
+    type: object
+    properties:
+      data:
+        type: array
+        items:
+          $ref: '#/components/schemas/User'
+      meta:
+        $ref: '#/components/schemas/PaginationMeta'
+```
+
+## Pagination — Cursor-Based
+
+```yaml
+schemas:
+  CursorPaginationMeta:
+    type: object
+    properties:
+      cursor:
+        type: string
+        nullable: true
+        description: Cursor for next page, null if no more pages
+        example: "eyJpZCI6MTAwfQ=="
+      hasMore:
+        type: boolean
+        example: true
+      limit:
+        type: integer
+        example: 20
+
+parameters:
+  CursorParam:
+    name: cursor
+    in: query
+    description: Pagination cursor from previous response
+    schema:
+      type: string
+```
+
+## Authentication Schemes
+
+```yaml
+components:
+  securitySchemes:
+    # JWT Bearer Token
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: JWT token obtained from /api/auth/login
+
+    # API Key in Header
+    apiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: API key provided during registration
+
+    # API Key in Query (less secure, use sparingly)
+    apiKeyQuery:
+      type: apiKey
+      in: query
+      name: api_key
+
+    # OAuth2 Authorization Code
+    oauth2Auth:
+      type: oauth2
+      flows:
+        authorizationCode:
+          authorizationUrl: https://auth.example.com/authorize
+          tokenUrl: https://auth.example.com/token
+          refreshUrl: https://auth.example.com/token
+          scopes:
+            read:users: Read user profiles
+            write:users: Create and update users
+            admin: Full administrative access
+
+    # Basic Auth
+    basicAuth:
+      type: http
+      scheme: basic
+
+# Apply globally (override per-operation with empty security: [])
+security:
+  - bearerAuth: []
+```
+
+## Common Headers
+
+```yaml
+parameters:
+  AcceptLanguageHeader:
+    name: Accept-Language
+    in: header
+    description: Preferred response language
+    schema:
+      type: string
+      default: en
+      example: en-US
+
+  IdempotencyKeyHeader:
+    name: Idempotency-Key
+    in: header
+    description: Unique key to ensure idempotent request processing
+    required: true
+    schema:
+      type: string
+      format: uuid
+      example: "550e8400-e29b-41d4-a716-446655440000"
+
+  CorrelationIdHeader:
+    name: X-Correlation-ID
+    in: header
+    description: Request correlation ID for tracing
+    schema:
+      type: string
+      format: uuid
+
+# Response headers
+headers:
+  X-Request-Id:
+    description: Unique request identifier for debugging
+    schema:
+      type: string
+      format: uuid
+
+  X-RateLimit-Limit:
+    description: Maximum requests allowed per window
+    schema:
+      type: integer
+      example: 100
+
+  X-RateLimit-Remaining:
+    description: Requests remaining in current window
+    schema:
+      type: integer
+      example: 95
+
+  X-RateLimit-Reset:
+    description: Unix timestamp when the rate limit resets
+    schema:
+      type: integer
+      example: 1700000000
+```
+
+## File Upload
+
+```yaml
+# Single file upload
+paths:
+  /api/uploads:
+    post:
+      tags: [Uploads]
+      summary: Upload a file
+      operationId: uploadFile
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required:
+                - file
+              properties:
+                file:
+                  type: string
+                  format: binary
+                  description: File to upload (max 10MB)
+                description:
+                  type: string
+                  description: Optional file description
+            encoding:
+              file:
+                contentType: image/png, image/jpeg, application/pdf
+      responses:
+        '201':
+          description: File uploaded successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                    format: uuid
+                  url:
+                    type: string
+                    format: uri
+                    example: "https://cdn.example.com/uploads/abc123.png"
+                  size:
+                    type: integer
+                    description: File size in bytes
+                    example: 204800
+                  mimeType:
+                    type: string
+                    example: "image/png"
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '413':
+          description: File too large
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  # Multiple file upload
+  /api/uploads/batch:
+    post:
+      tags: [Uploads]
+      summary: Upload multiple files
+      operationId: uploadFiles
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required:
+                - files
+              properties:
+                files:
+                  type: array
+                  items:
+                    type: string
+                    format: binary
+                  maxItems: 5
+      responses:
+        '201':
+          description: Files uploaded successfully
+```
+
+## File Download
+
+```yaml
+paths:
+  /api/uploads/{fileId}/download:
+    get:
+      tags: [Uploads]
+      summary: Download a file
+      operationId: downloadFile
+      parameters:
+        - name: fileId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: File content
+          headers:
+            Content-Disposition:
+              schema:
+                type: string
+                example: 'attachment; filename="report.pdf"'
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '404':
+          $ref: '#/components/responses/NotFound'
+```
+
+## CRUD Resource Template
+
+Complete pattern for a typical resource:
+
+```yaml
+paths:
+  /api/resources:
+    get:
+      tags: [Resources]
+      summary: List all resources
+      operationId: listResources
+      parameters:
+        - $ref: '#/components/parameters/PageParam'
+        - $ref: '#/components/parameters/LimitParam'
+        - $ref: '#/components/parameters/SortByParam'
+        - $ref: '#/components/parameters/SortOrderParam'
+        - name: search
+          in: query
+          description: Search by name or description
+          schema:
+            type: string
+        - name: status
+          in: query
+          description: Filter by status
+          schema:
+            type: string
+            enum: [active, inactive, archived]
+      responses:
+        '200':
+          description: Paginated list of resources
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaginatedResourceList'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+    post:
+      tags: [Resources]
+      summary: Create a new resource
+      operationId: createResource
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateResourceRequest'
+      responses:
+        '201':
+          description: Resource created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Resource'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+  /api/resources/{id}:
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: Resource unique identifier
+        schema:
+          type: string
+          format: uuid
+
+    get:
+      tags: [Resources]
+      summary: Get resource by ID
+      operationId: getResource
+      responses:
+        '200':
+          description: Resource details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Resource'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    put:
+      tags: [Resources]
+      summary: Update a resource
+      operationId: updateResource
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateResourceRequest'
+      responses:
+        '200':
+          description: Resource updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Resource'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    delete:
+      tags: [Resources]
+      summary: Delete a resource
+      operationId: deleteResource
+      responses:
+        '204':
+          description: Resource deleted
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+```
+
+## Webhook Callback Pattern
+
+```yaml
+paths:
+  /api/webhooks:
+    post:
+      tags: [Webhooks]
+      summary: Register a webhook
+      operationId: registerWebhook
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - url
+                - events
+              properties:
+                url:
+                  type: string
+                  format: uri
+                  example: "https://your-app.com/webhook"
+                events:
+                  type: array
+                  items:
+                    type: string
+                    enum:
+                      - resource.created
+                      - resource.updated
+                      - resource.deleted
+                secret:
+                  type: string
+                  description: Shared secret for HMAC signature verification
+      callbacks:
+        onEvent:
+          '{$request.body#/url}':
+            post:
+              summary: Webhook event payload
+              requestBody:
+                content:
+                  application/json:
+                    schema:
+                      type: object
+                      properties:
+                        event:
+                          type: string
+                          example: "resource.created"
+                        timestamp:
+                          type: string
+                          format: date-time
+                        data:
+                          type: object
+              responses:
+                '200':
+                  description: Acknowledged
+```
+
+## Health Check Endpoint
+
+```yaml
+paths:
+  /health:
+    get:
+      tags: [System]
+      summary: Health check
+      operationId: healthCheck
+      security: []
+      responses:
+        '200':
+          description: Service is healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum: [healthy, degraded]
+                    example: healthy
+                  version:
+                    type: string
+                    example: "1.2.3"
+                  uptime:
+                    type: integer
+                    description: Uptime in seconds
+                    example: 86400
+                  dependencies:
+                    type: object
+                    properties:
+                      database:
+                        type: string
+                        enum: [connected, disconnected]
+                      cache:
+                        type: string
+                        enum: [connected, disconnected]
+```