docs: improve documentation across all configuration files

- Add detailed CI/CD workflow documentation
- Enhance config.yaml with comprehensive comments
- Add schemas/README.md with JSON schema documentation
- Add data/README.md with test data documentation
- Improve setup.sh script documentation

Author: SaahilParmar

.github/workflows/ci.yml

@@ -1,3 +1,25 @@
+# API Test Automation Framework - CI/CD Pipeline
+# This workflow automates testing, security scanning, and documentation deployment
+# for the API Test Automation Framework.
+#
+# Triggers:
+# - Push to main/develop/fix/feature branches
+# - Pull requests to main
+# - Daily at 6 AM UTC (Scheduled health check)
+# - Manual trigger (workflow_dispatch)
+#
+# Jobs:
+# 1. test: Runs test suite across Python versions
+# 2. security-scan: Performs security analysis
+# 3. performance-test: Runs performance tests
+# 4. deploy-docs: Deploys documentation to GitHub Pages
+# 5. notify: Sends notifications on failure
+#
+# Environment Setup:
+# - Uses Python matrix strategy (3.10, 3.11, 3.12)
+# - Caches pip dependencies
+# - Sets up Java for Allure reporting
+
 name: API Test Automation CI/CD
 
 'on':
@@ -6,9 +28,9 @@ name: API Test Automation CI/CD
   pull_request:
     branches: [ main ]
   schedule:
-    # Run tests daily at 6 AM UTC
+    # Run tests daily at 6 AM UTC for health check
     - cron: '0 6 * * *'
-  workflow_dispatch:
+  workflow_dispatch:  # Allows manual trigger
 
 # Add concurrency control to prevent resource conflicts
 concurrency:

config/config.yaml

@@ -1,8 +1,30 @@
-# config.yaml
+# config.yaml - Framework Configuration
 # -----------------------------------------------------------------------------
-# Configuration file for environment settings and global test behavior.
-# This file controls which environment is active, API endpoints, authentication,
-# request timeouts, retry logic, and default HTTP headers for all API tests.
+# Main configuration file for the API Test Automation Framework.
+#
+# Configuration Categories:
+# 1. Environment Selection
+#    - Controls which environment (dev/staging) is active
+#    - Defines environment-specific settings
+#
+# 2. API Settings
+#    - Base URLs for different environments
+#    - Authentication tokens and credentials
+#    - Default request timeouts
+#
+# 3. Test Behavior
+#    - Retry logic for flaky tests
+#    - Default HTTP headers
+#    - Logging levels
+#
+# 4. Performance Settings
+#    - Request timeouts
+#    - Rate limiting
+#    - Concurrent request limits
+#
+# Usage:
+# The framework automatically loads this configuration via utils.api_utils.load_config()
+# Override settings using environment variables where needed
 # -----------------------------------------------------------------------------
 
 # Select which environment to use: dev or staging

data/README.md

@@ -0,0 +1,49 @@
+# Test Data Documentation
+
+This directory contains test data used by the API Test Automation Framework.
+
+## Data Files
+
+### 1. post_user_payloads.json
+Contains test data for user creation tests (POST /api/users):
+- Valid user data with different combinations
+- Edge cases for validation
+- Various job titles and user names
+
+### 2. large_payload.json
+Test data for performance and boundary testing:
+- Large data payload (>1MB)
+- Complex nested structures
+- Used for testing API handling of large requests
+
+## Data Structure
+Each test data file follows a specific structure for consistent testing:
+```json
+[
+    {
+        "name": "test user name",
+        "job": "test job title",
+        "expectedStatus": 201,
+        "description": "Test case description"
+    }
+]
+```
+
+## Usage
+The test data is loaded and used in parameterized tests:
+```python
+import json
+def load_test_data():
+    with open("data/post_user_payloads.json") as f:
+        return json.load(f)
+
+@pytest.mark.parametrize("payload", load_test_data())
+def test_create_user(payload):
+    # Test implementation
+```
+
+## Maintenance
+- Keep data files under 5MB
+- Use meaningful test data that represents real-world scenarios
+- Include both positive and negative test cases
+- Document special test cases or edge conditions

schemas/README.md

@@ -0,0 +1,50 @@
+# API Schema Documentation
+
+This directory contains JSON Schema definitions for validating API responses from the ReqRes API.
+
+## Schema Files
+
+### 1. user_list_schema.json
+- **Endpoint**: GET /api/users?page={page}
+- **Purpose**: Validates paginated user list responses
+- **Key Properties**:
+  - page: Current page number
+  - per_page: Items per page
+  - total: Total number of users
+  - data: Array of user objects
+  - support: Support information
+
+### 2. single_user_schema.json
+- **Endpoint**: GET /api/users/{id}
+- **Purpose**: Validates single user responses
+- **Key Properties**:
+  - data: Single user object
+  - support: Support information
+
+### 3. create_user_schema.json
+- **Endpoint**: POST /api/users
+- **Purpose**: Validates user creation response
+- **Key Properties**:
+  - name: User's name
+  - job: User's job
+  - id: Generated user ID
+  - createdAt: Creation timestamp
+
+## Schema Validation
+All schemas are JSON Schema Draft-07 compliant and are used in the test suite for response validation. They ensure that:
+- Required fields are present
+- Field types are correct
+- Data structures are consistent
+- Additional properties are handled appropriately
+
+## Usage Example
+```python
+from jsonschema import validate
+from utils.api_utils import load_schema
+
+# Load schema
+schema = load_schema('user_list_schema.json')
+
+# Validate response
+validate(instance=response.json(), schema=schema)
+```

schemas/user_list_schema.json

@@ -1,6 +1,13 @@
 {
+  // User List Response Schema
+  // This schema validates the response from GET /api/users endpoint
+  // It defines the structure for paginated user list responses
+  // Version: 1.0.0
+  // Last Updated: 2025-07-11
+  // Endpoint: GET /api/users?page={page}
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "UserListResponse",
+  "description": "Schema for paginated user list response from ReqRes API",
   "type": "object",
   "required": ["page", "per_page", "total", "total_pages", "data", "support"],
   "properties": {

setup.sh

@@ -1,7 +1,24 @@
 #!/bin/bash
 
-# setup.sh - Setup script for API Test Automation Framework
-# This script sets up the virtual environment and installs dependencies
+# setup.sh - Environment Setup Script
+# -----------------------------------------------------------------------------
+# This script automates the setup process for the API Test Automation Framework.
+# It performs the following tasks:
+# 1. Validates Python installation
+# 2. Creates/activates virtual environment (.venv)
+# 3. Installs project dependencies
+# 4. Sets up Allure reporting
+# 5. Validates schema and data files
+#
+# Usage:
+#   ./setup.sh          # Standard setup
+#   ./setup.sh --force  # Force reinstall of dependencies
+#
+# Requirements:
+#   - Python 3.10 or higher
+#   - pip package manager
+#   - bash-compatible shell
+# -----------------------------------------------------------------------------
 
 set -e