feat: add OpenAPI auto-generate dari routes - Tambah OpenAPIGenerator class untuk scan routes dan generate spec - Tambah CLI command bin/generate-openapi.php - Support auto-generate on request via OPENAPI_AUTO_GENERATE env - Update public/index.php untuk auto-generate saat request /docs/openapi.json - Tambah dokumentasi OPENAPI_AUTO_GENERATE.md

2025-12-18 06:53:52 +07:00
parent eaa8ca97c1
commit 5af51949db
4 changed files with 764 additions and 1 deletions
--- a/docs/OPENAPI_AUTO_GENERATE.md
+++ b/docs/OPENAPI_AUTO_GENERATE.md
@@ -0,0 +1,197 @@
+# 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
+