# 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:**
```json
{
  "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:**
```json
{
  "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.