api-btekno/docs/OPENAPI_AUTO_GENERATE.md

# OpenAPI Auto-Generate

Sistem auto-generate OpenAPI spec dari routes yang terdaftar di Slim Framework.

## 🎯 Fitur

- **Auto-generate dari routes** - Scan semua routes yang terdaftar dan generate OpenAPI spec
- **CLI command** - Generate via command line
- **On-demand generation** - Auto-generate saat request `/docs/openapi.json` (optional)
- **No manual update** - Tidak perlu update manual `openapi.json` setiap kali tambah endpoint

## 📋 Cara Menggunakan

### Opsi 1: CLI Command (Recommended)

Generate OpenAPI spec via command line:

```bash
php bin/generate-openapi.php
```

Output default: `public/docs/openapi.json`

Custom output file:
```bash
php bin/generate-openapi.php --output custom/path/openapi.json
```

**Note:** CLI command memerlukan database connection karena routes perlu di-register.

### Opsi 2: Auto-Generate on Request

Enable auto-generate saat request `/docs/openapi.json`:

1. Tambahkan di `.env`:
```env
OPENAPI_AUTO_GENERATE=true
```

2. Setiap request ke `/docs/openapi.json` akan:
   - Generate OpenAPI spec dari routes yang terdaftar
   - Save ke file `public/docs/openapi.json`
   - Return JSON response

**Keuntungan:**
- ✅ Selalu up-to-date dengan routes terbaru
- ✅ Tidak perlu manual update
- ✅ Swagger UI otomatis menampilkan endpoint baru

**Kekurangan:**
- ⚠️ Perlu database connection (routes butuh DB untuk register)
- ⚠️ Sedikit overhead saat request (generate setiap kali)

### Opsi 3: Manual Update (Default)

Default behavior: load dari file `public/docs/openapi.json`.

Jika `OPENAPI_AUTO_GENERATE=false` atau tidak di-set, akan load dari file.

## 🔧 Konfigurasi

### Environment Variables

```env
# Enable auto-generate on request
OPENAPI_AUTO_GENERATE=true

# Default: false (load from file)
```

### File Locations

- **Generator class:** `src/Support/OpenAPIGenerator.php`
- **CLI script:** `bin/generate-openapi.php`
- **Output file:** `public/docs/openapi.json`
- **Swagger UI:** `/docs`

## 📝 Cara Kerja

1. **Scan Routes** - Generator scan semua routes yang terdaftar di Slim App
2. **Extract Metadata** - Extract method, path, parameters, security dari routes
3. **Generate Schema** - Generate request/response schema berdasarkan path patterns
4. **Build OpenAPI Spec** - Build complete OpenAPI 3.0 spec
5. **Save/Return** - Save ke file atau return sebagai JSON

## 🎨 Customization

### Custom Request Body Schema

Edit method `getRequestBodySchema()` di `src/Support/OpenAPIGenerator.php`:

```php
private function getRequestBodySchema(string $pattern, $callable): ?array
{
    // Add custom schema based on path pattern
    if (strpos($pattern, '/custom-endpoint') !== false) {
        return [
            'required' => true,
            'content' => [
                'application/json' => [
                    'schema' => [
                        'type' => 'object',
                        'properties' => [
                            'field1' => ['type' => 'string'],
                            'field2' => ['type' => 'integer']
                        ]
                    ]
                ]
            ]
        ];
    }
    // ...
}
```

### Custom Tags

Edit method `getTagFromPath()` untuk custom tag assignment:

```php
private function getTagFromPath(string $path): string
{
    if (strpos($path, '/custom') !== false) {
        return 'Custom';
    }
    // ...
}
```

### Custom Parameters

Edit method `extractParameters()` untuk custom query parameters:

```php
private function extractParameters(string $pattern): array
{
    $parameters = [];
    
    // Add custom query params
    if (strpos($pattern, '/custom') !== false) {
        $parameters[] = [
            'name' => 'custom_param',
            'in' => 'query',
            'schema' => ['type' => 'string']
        ];
    }
    
    return $parameters;
}
```

## 🚀 Workflow

### Development

1. Tambah endpoint baru di routes
2. Run `php bin/generate-openapi.php`
3. Commit `openapi.json` yang ter-update
4. Swagger UI otomatis menampilkan endpoint baru

### Production (with auto-generate)

1. Set `OPENAPI_AUTO_GENERATE=true` di `.env`
2. Tambah endpoint baru di routes
3. Deploy
4. Swagger UI otomatis menampilkan endpoint baru (no commit needed)

### Production (without auto-generate)

1. Tambah endpoint baru di routes
2. Run `php bin/generate-openapi.php` di local/staging
3. Commit `openapi.json` yang ter-update
4. Deploy (include updated `openapi.json`)

## ⚠️ Limitations

1. **Database Required** - Routes perlu database connection untuk register
2. **Schema Inference** - Request body schema di-infer dari path pattern (bisa kurang akurat)
3. **No Reflection** - Tidak scan controller methods untuk extract detailed schema
4. **Manual Customization** - Complex schemas perlu manual edit di generator

## 🔮 Future Improvements

- [ ] Support PHP annotations untuk detailed schema
- [ ] Reflection-based schema extraction dari controller methods
- [ ] Support untuk custom OpenAPI extensions
- [ ] Cache generated spec untuk performance
- [ ] Support untuk multiple OpenAPI versions

## 📚 Related Files

- `src/Support/OpenAPIGenerator.php` - Generator class
- `bin/generate-openapi.php` - CLI script
- `public/index.php` - Auto-generate on request handler
- `public/docs/openapi.json` - Generated OpenAPI spec
- `public/docs/index.html` - Swagger UI