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:

php bin/generate-openapi.php

Output default: public/docs/openapi.json

Custom output file:

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:

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

# 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:

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:

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

Custom Parameters

Edit method extractParameters() untuk custom query parameters:

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