corrad-af-2024/docs/API_ACCESS_GUIDE.md

API Documentation Access Guide

This guide explains how to access and use the comprehensive API documentation for the Corrad AF 2024 API Platform.

🌐 Live API Documentation

Scalar API Reference (Interactive Documentation)

URL: http://localhost:3000/api-docs

• Interactive Interface: Modern, user-friendly API explorer
• Try It Out: Test API endpoints directly from the documentation
• Multiple Themes: Choose from 10+ beautiful themes
• Real-time Testing: Send requests and see responses immediately
• Authentication: Built-in support for Bearer token authentication

OpenAPI Specification (Swagger JSON)

URL: http://localhost:3000/api/openapi

• Dynamic Server URLs: Automatically detects your current host
• Complete Specification: All 79+ endpoints documented
• Import Ready: Use with Postman, Insomnia, or other API tools
• Cache Optimized: 5-minute cache for better performance

Static OpenAPI File

URL: http://localhost:3000/openapi.json

• Static Version: Original OpenAPI specification file
• Backup Access: Alternative if dynamic endpoint is unavailable

📱 Access Methods

1. Browser Access

Open any web browser and navigate to:

http://localhost:3000/api-docs

2. Postman Import

1. Open Postman
2. Click "Import" → "Link"
3. Enter: http://localhost:3000/api/openapi
4. Click "Continue" → "Import"

3. Insomnia Import

1. Open Insomnia
2. Click "Create" → "Import From" → "URL"
3. Enter: http://localhost:3000/api/openapi
4. Click "Fetch and Import"

4. Swagger UI

Use any Swagger UI instance with the URL:

http://localhost:3000/api/openapi

5. curl Access

Fetch the OpenAPI specification:

curl http://localhost:3000/api/openapi

🔧 Features

Interactive Documentation

• Modern UI: Clean, responsive design
• Code Examples: Request/response examples for all endpoints
• Authentication: Integrated login and token management
• Real-time Testing: Send actual requests to the API
• Multiple Formats: JSON, form-data, and URL-encoded support

API Categories

1. Authentication (3 endpoints)
   • Login, logout, token validation
2. Business Logic (1 endpoint)
   • Asnaf profile analysis with AI
3. API Platform (3 endpoints)
   • HTTP proxy, OAuth2 flows
4. Metabase Integration (1 endpoint)
   • Analytics token management
5. Development Tools (70+ endpoints)
   • User, role, menu management
   • Database operations
   • Content management
   • Configuration tools

Authentication

Most endpoints require a Bearer token. To authenticate:

1. Use the /api/auth/login endpoint
2. Copy the returned token
3. Add to Authorization header: Bearer <your-token>

🎨 Customization

Theme Options

Access the settings panel in the documentation to choose from:

• Default
• Alternate
• Moon (Dark)
• Purple
• Solarized
• Blue Planet
• Saturn
• Kepler
• Mars
• Deep Space

Layout Options

• Modern: Three-column layout with sidebar
• Classic: Two-column traditional layout

🚀 Quick Start

1. Start the Server

   npm run dev
   # or
   yarn dev
   

2. Access Documentation Open: http://localhost:3000/api-docs

3. Authenticate

   • Use the login endpoint
   • Enter your credentials
   • Token will be automatically saved

4. Explore APIs

   • Browse by category
   • Try the "Send Request" button
   • View real responses

🔗 URLs Summary

Service	URL	Description
Interactive Docs	http://localhost:3000/api-docs	Main API documentation interface
OpenAPI Spec	http://localhost:3000/api/openapi	Dynamic OpenAPI JSON
Static Spec	http://localhost:3000/openapi.json	Static OpenAPI file
Postman Collection	./postman_collection.json	Ready-to-import Postman collection
Preview Mode	http://localhost:3000/api-docs?preview=true	Preview with custom settings

📋 Postman Collection

A complete Postman collection is available in the root directory:

• File: postman_collection.json
• Endpoints: All 79+ API endpoints
• Environment: Pre-configured variables
• Authentication: Automatic token management
• Examples: Sample requests and responses

🔧 Troubleshooting

White Screen Issue (Fixed)

• Improved CSS styling for proper height management
• Better scrolling behavior
• Enhanced container management

Common Issues

1. Documentation not loading: Check if server is running on port 3000
2. Authentication errors: Ensure valid token in Authorization header
3. CORS issues: Use the built-in proxy for external API calls
4. Theme not applying: Clear browser cache and reload

Development URLs

Replace localhost:3000 with your actual server URL when deployed.

📞 Support

For API support and questions:

• Email: support@corradaf.com
• Documentation: This interactive documentation
• Postman Collection: Available in project root

---

Note: This documentation is automatically updated with server information and includes all implemented endpoints from the codebase.