corrad-af-2024/docs/OPENAPI_CONFIGURATION_GUIDE.md

OpenAPI Configuration Guide

This guide explains how to configure and use the enhanced OpenAPI documentation features in the Corrad AF 2024 API Platform.

Overview

The platform now supports three methods for providing OpenAPI specifications:

1. OpenAPI URL - Traditional URL-based specification loading
2. Generate from Collections - Auto-generate from saved API collections
3. Custom JSON - Manual specification editing with validation

Access Configuration

Navigate to your API platform and open the Scalar Configuration Modal to access these features:

1. Go to /api-platform
2. Look for the "API Documentation Settings" or configuration icon
3. Click on the Basic Info tab

Configuration Options

1. OpenAPI URL (Default)

Use this option when you have an existing OpenAPI specification available via URL.

Features:

• Support for both JSON and Markdown files
• Dynamic server URL detection
• Proxy support for CORS issues

Usage:

1. Select "OpenAPI URL" radio button
2. Enter your specification URL in the "OpenAPI Specification URL" field
3. Optionally configure a proxy URL if needed

2. Generate from Collections

Automatically generate OpenAPI specifications from your saved API collections.

Features:

• Auto-detection of endpoints from collections
• Schema inference from request/response bodies
• Automatic tagging by collection names
• Parameter extraction from queries and headers

Usage:

1. Select "Generate from Collections" radio button
2. Review available collections displayed
3. Click "Generate" button
4. The system will:
   • Create an OpenAPI 3.0.3 specification
   • Generate markdown documentation
   • Save to /docs/openapi-collections.md
   • Switch to custom editor for review

Generated Features:

• Collection names become API tags
• Request names become operation summaries
• Query parameters and headers become OpenAPI parameters
• Request bodies are analyzed for schema generation
• Basic response schemas (success/error) are included

3. Custom JSON

Manually create or edit OpenAPI specifications with real-time validation.

Features:

• Live JSON validation
• File import support (JSON/YAML)
• Syntax highlighting
• Error reporting
• Auto-save functionality

Usage:

1. Select "Custom JSON" radio button
2. Either:
   • Paste JSON directly into the editor
   • Click "Import" to upload a file
   • Use "Generate" from collections first, then edit
3. The editor provides:
   • Real-time validation feedback
   • Error highlighting
   • Valid JSON confirmation
4. Click "Save Custom JSON" to save changes

File Management

Generated Files

When using collection generation or custom JSON, files are saved to:

• Collections: /docs/openapi-collections.md
• Custom: /docs/openapi-custom.md
• Original: /docs/openapi.md

File Access

All generated files are accessible via:

• Web Interface: /api-docs (interactive documentation)
• Direct Access: /docs/[filename] (raw file content)
• API Endpoint: /api/openapi (dynamic markdown)

API Endpoints

Generate from Collections

POST /api/openapi/generate-from-collections

Request Body:

{
  "collections": [/* array of collections */],
  "config": {
    "title": "API Title",
    "description": "API Description", 
    "version": "1.0.0",
    "contact": {
      "name": "Support",
      "email": "support@example.com"
    }
  }
}

Save OpenAPI File

POST /api/docs/save-openapi

Request Body:

{
  "content": "file content",
  "filename": "openapi.md"
}

Serve Documentation Files

GET /docs/[filename]

Schema Generation

When generating from collections, the system automatically:

1. Infers Request Schemas

• Parses JSON request bodies
• Creates type-appropriate schemas
• Handles nested objects and arrays
• Provides example values

2. Creates Parameters

• Query parameters from URL params
• Header parameters (excluding standard headers)
• Path parameters from URL structure

3. Generates Responses

• Standard success/error response schemas
• Content-type detection
• Status code mapping

4. Security Configuration

• Automatic bearer token detection
• Auth method mapping from collection settings

Best Practices

Collection Organization

1. Naming: Use descriptive collection names (become API tags)
2. Grouping: Group related endpoints in same collection
3. Documentation: Add descriptions to requests for better summaries

Request Configuration

1. URLs: Use full URLs with proper base paths
2. Parameters: Configure active parameters with descriptions
3. Bodies: Use valid JSON for better schema inference
4. Headers: Include necessary headers, exclude standard ones

Custom Editing

1. Validation: Always validate before saving
2. Backup: Export configurations before major changes
3. Testing: Use preview mode to test changes
4. Structure: Follow OpenAPI 3.0.3 specification

Troubleshooting

Common Issues

Generation Fails

• Ensure collections contain valid requests
• Check request URLs are properly formatted
• Verify JSON bodies are valid

Validation Errors

• Missing required OpenAPI fields (openapi, info)
• Invalid JSON syntax
• Incorrect schema structure

Display Issues

• Check markdown JSON extraction
• Verify Scalar initialization
• Review browser console for errors

Debug Mode

Enable debug logging by checking browser console when:

• Configuration loading fails
• Generation produces unexpected results
• Scalar fails to initialize

Migration Guide

From Static OpenAPI

1. Access configuration modal
2. Select "Custom JSON"
3. Import existing specification
4. Save as new file
5. Update configuration

From External URLs

1. Download current specification
2. Use "Custom JSON" import feature
3. Edit as needed
4. Save locally for better control

Integration Examples

Postman Integration

1. Generate or configure OpenAPI spec
2. Access via /docs/openapi-collections.md
3. Extract JSON from markdown
4. Import into Postman

Insomnia Integration

1. Use same process as Postman
2. Import OpenAPI JSON directly
3. All endpoints and schemas preserved

Development Workflow

1. Create API collections during development
2. Generate OpenAPI specification automatically
3. Review and edit as needed
4. Deploy documentation
5. Keep collections updated for regeneration

This enhanced system provides flexibility while maintaining automation, allowing both rapid prototyping and detailed customization of API documentation.