ai-flow-dev 2.1.3 → 2.1.4

package/templates/backend/docs/api.template.md

@@ -12,14 +12,13 @@
 
 **Base URL(s):**
 {{#EACH API_BASE_URL}}
+
 - {{ENVIRONMENT}}: `{{URL}}`
-{{/EACH}}
+  {{/EACH}}
 
 **Versioning Strategy:** {{API_VERSIONING_STRATEGY}}
 
-**Default Content Type:** `{{DEFAULT_CONTENT_TYPE}}`
-
----
+## **Default Content Type:** `{{DEFAULT_CONTENT_TYPE}}`
 
 ## 🔐 Authentication & Authorization
 
@@ -28,11 +27,13 @@
 **Mechanism:** {{AUTH_MECHANISM}}
 
 **Token/Session Flow:**
+
 ```
 {{AUTH_FLOW_DIAGRAM}}
 ```
 
 **Token Structure:**
+
 ```json
 {{AUTH_TOKEN_EXAMPLE}}
 ```
@@ -57,7 +58,8 @@
 ### Headers
 
 | Header | Required | Description |
-|--------|----------|-------------|
+| ------ | -------- | ----------- |
+
 {{#EACH REQUEST_HEADER}}
 | `{{HEADER_NAME}}` | {{IS_REQUIRED}} | {{HEADER_DESCRIPTION}} |
 {{/EACH}}
@@ -78,8 +80,9 @@
 ### Validation Rules
 
 {{#EACH VALIDATION_RULE}}
+
 - {{RULE_DESCRIPTION}}
-{{/EACH}}
+  {{/EACH}}
 
 ---
 
@@ -92,7 +95,8 @@
 ### Envelope Structure
 
 | Field | Description |
-|-------|-------------|
+| ----- | ----------- |
+
 {{#EACH RESPONSE_FIELD}}
 | `{{FIELD_NAME}}` | {{FIELD_DESCRIPTION}} |
 {{/EACH}}
@@ -111,21 +115,74 @@
 {{ERROR_RESPONSE_EXAMPLE}}
 ```
 
-| HTTP Code | Error Code | Message | Description |
-|-----------|------------|---------|-------------|
-{{#EACH ERROR_MAPPING}}
-| {{HTTP_CODE}} | `{{ERROR_CODE}}` | {{ERROR_MESSAGE}} | {{ERROR_DESCRIPTION}} |
+### Error Codes Catalog
+
+| Code | HTTP | Message | Resolution |
+| ---- | ---- | ------- | ---------- |
+
+{{#EACH ERROR_CODE}}
+| `{{CODE}}` | {{HTTP_STATUS}} | {{MESSAGE}} | {{RESOLUTION}} |
 {{/EACH}}
 
+### Error Categories
+
+| Category       | Code Range     | Description                         |
+| -------------- | -------------- | ----------------------------------- |
+| Validation     | `VALIDATION_*` | Input validation failures           |
+| Authentication | `AUTH_*`       | Authentication/authorization errors |
+| Resource       | `RESOURCE_*`   | Resource not found, conflict errors |
+| Business       | `BIZ_*`        | Business rule violations            |
+| System         | `SYS_*`        | Internal system errors              |
+
 **Retry Policy:** {{RETRY_POLICY}}
 
 **Idempotency:** {{IDEMPOTENCY_POLICY}}
 
+### Idempotency Keys
+
+**Header:** `{{IDEMPOTENCY_HEADER}}`
+**Storage:** {{IDEMPOTENCY_STORAGE}}
+**TTL:** {{IDEMPOTENCY_TTL}}
+
+**Endpoints requiring idempotency:**
+{{#EACH IDEMPOTENT_ENDPOINT}}
+
+- `{{METHOD}} {{PATH}}` - {{DESCRIPTION}}
+  {{/EACH}}
+
+---
+
+## 📐 Validation Rules Catalog
+
+### Global Field Validation
+
+| Field Type | Rules | Error Message |
+| ---------- | ----- | ------------- |
+
+{{#EACH VALIDATION_FIELD_TYPE}}
+| `{{TYPE}}` | {{RULES}} | {{ERROR_MESSAGE}} |
+{{/EACH}}
+
+### Entity-Specific Validation
+
+{{#EACH ENTITY_VALIDATION}}
+
+#### {{ENTITY_NAME}}
+
+| Field | Rules | Required |
+| ----- | ----- | -------- |
+
+{{#EACH FIELD}}
+| `{{NAME}}` | {{RULES}} | {{REQUIRED}} |
+{{/EACH}}
+{{/EACH}}
+
 ---
 
 ## 📚 Resource Catalogue
 
 {{#EACH RESOURCE}}
+
 ### {{RESOURCE_NAME}}
 
 **Base Path:** `{{RESOURCE_BASE_PATH}}`
@@ -135,7 +192,8 @@
 #### Standard Endpoints
 
 | Method | Path | Auth | Description |
-|--------|------|------|-------------|
+| ------ | ---- | ---- | ----------- |
+
 {{#EACH RESOURCE_ENDPOINT}}
 | {{METHOD}} | `{{PATH}}` | {{AUTH_REQUIRED}} | {{ENDPOINT_DESCRIPTION}} |
 {{/EACH}}
@@ -153,46 +211,57 @@
 ```
 
 #### Business Rules
+
 {{#EACH RESOURCE_RULE}}
+
 - {{RULE_DESCRIPTION}}
-{{/EACH}}
+  {{/EACH}}
 
 #### Related Entities
+
 {{#EACH RESOURCE_RELATION}}
+
 - {{RELATION_DESCRIPTION}}
-{{/EACH}}
+  {{/EACH}}
 
 ---
+
 {{/EACH}}
 
 ## ⚙️ Custom Endpoints & Actions
 
 {{#EACH CUSTOM_ENDPOINT}}
+
 ### {{ENDPOINT_NAME}}
 
 - **Method:** {{METHOD}}
 - **URL:** `{{URL}}`
 - **Purpose:** {{PURPOSE}}
 - **Request Schema:**
+
 ```json
 {{REQUEST_SCHEMA}}
 ```
+
 - **Response Schema:**
+
 ```json
 {{RESPONSE_SCHEMA}}
 ```
+
 - **Special Considerations:** {{CONSIDERATIONS}}
 
 ---
+
 {{/EACH}}
 
 ## 📈 Rate Limiting
 
 - **Strategy:** {{RATE_LIMIT_STRATEGY}}
 - **Limits:**
-{{#EACH RATE_LIMIT}}
+  {{#EACH RATE_LIMIT}}
   - {{LIMIT_SCOPE}}: {{LIMIT_VALUE}} requests per {{LIMIT_WINDOW}}
-{{/EACH}}
+    {{/EACH}}
 - **Headers:** `{{RATE_LIMIT_HEADERS}}`
 
 ---
@@ -204,7 +273,7 @@
 - **Contract Tests:** {{CONTRACT_TESTS_STATUS}}
 
 ```yaml
-{{OPENAPI_SNIPPET}}
+{ { OPENAPI_SNIPPET } }
 ```
 
 ---
@@ -230,19 +299,19 @@
 ## 🔧 Tooling & Integration Guides
 
 {{#EACH SDK}}
+
 ### {{SDK_NAME}} SDK
 
 - **Language:** {{SDK_LANGUAGE}}
 - **Package:** `{{SDK_PACKAGE}}`
 - **Installation:** `{{SDK_INSTALL_COMMAND}}`
 - **Usage Example:**
+
 ```{{SDK_LANGUAGE}}
 {{SDK_USAGE_EXAMPLE}}
 ```
 
-{{/EACH}}
-
----
+## {{/EACH}}
 
 **Document Version:** 1.0