diff --git a/app/Config/Routes.php b/app/Config/Routes.php index db85d70..6d79622 100644 --- a/app/Config/Routes.php +++ b/app/Config/Routes.php @@ -21,12 +21,6 @@ $routes->group('api', ['filter' => 'auth'], function ($routes) { -// Swagger API Documentation (public - no filters) -$routes->add('swagger', 'PagesController::swagger'); - -// OpenAPI Specification (server-side merged - public) -$routes->get('api-docs', 'OpenApiDocs::index'); - // V2 Auth API Routes (public - no auth required) $routes->group('v2/auth', function ($routes) { $routes->post('login', 'AuthV2Controller::login'); diff --git a/app/Controllers/OpenApiDocs.php b/app/Controllers/OpenApiDocs.php deleted file mode 100644 index 95ccbc5..0000000 --- a/app/Controllers/OpenApiDocs.php +++ /dev/null @@ -1,43 +0,0 @@ -response - ->setContentType('application/x-yaml') - ->setHeader('Access-Control-Allow-Origin', '*') - ->setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS') - ->setHeader('Access-Control-Allow-Headers', 'Content-Type') - ->setHeader('Cache-Control', 'no-cache, must-revalidate') - ->setBody($content); - - } catch (\Exception $e) { - log_message('error', 'OpenApiDocs Error: ' . $e->getMessage()); - return $this->response - ->setStatusCode(500) - ->setContentType('application/json') - ->setBody(json_encode([ - 'error' => 'Failed to serve OpenAPI spec', - 'message' => $e->getMessage() - ])); - } - } -} diff --git a/app/Controllers/PagesController.php b/app/Controllers/PagesController.php index 4291507..90c1ee1 100644 --- a/app/Controllers/PagesController.php +++ b/app/Controllers/PagesController.php @@ -10,13 +10,5 @@ namespace App\Controllers; */ class PagesController extends BaseController { - - - /** - * API Documentation / Swagger UI page - */ - public function swagger() - { - return view('swagger'); - } + // Add page methods here as needed } diff --git a/app/Views/swagger.php b/app/Views/swagger.php deleted file mode 100644 index e08665b..0000000 --- a/app/Views/swagger.php +++ /dev/null @@ -1,405 +0,0 @@ - - - - - - API Documentation - CLQMS - - - - - - - -
-

Resources

- -
-
- - - - - - - - diff --git a/public/API_DOCS_README.md b/public/API_DOCS_README.md deleted file mode 100644 index 511ea71..0000000 --- a/public/API_DOCS_README.md +++ /dev/null @@ -1,162 +0,0 @@ -# CLQMS OpenAPI Documentation Structure - -## Overview - -The OpenAPI documentation has been reorganized into a modular structure for better maintainability. - -**Architecture:** Server-side resolution (CodeIgniter 4) -- Modular files in `paths/` and `components/schemas/` directories -- CodeIgniter controller merges files on-the-fly -- Single endpoint `/api-docs` serves complete specification -- No build step or bundling required - -## How It Works - -1. **Modular Development:** Edit files in `paths/` and `components/schemas/` -2. **Server-Side Merge:** `OpenApiDocs` controller loads and merges all files -3. **Single Endpoint:** Access `/api-docs` to get complete merged specification -4. **Cache Support:** Can add caching layer for production - -## Recommended Usage - -**For Swagger UI:** Use the CodeIgniter route `/api-docs` (already configured in `app/Views/swagger.php`) - -**For development:** Edit modular files directly - changes are reflected immediately on next request - -## Structure - - -``` -public/ -├── api-docs.yaml # Main entry point with schema references -├── api-docs.bundled.yaml # Bundled version (use this for Swagger UI) -├── components/ -│ └── schemas/ -│ ├── authentication.yaml -│ ├── common.yaml -│ ├── edge-api.yaml -│ ├── master-data.yaml -│ ├── orders.yaml -│ ├── organization.yaml -│ ├── patient-visit.yaml -│ ├── patient.yaml -│ ├── specimen.yaml -│ ├── tests.yaml -│ └── valuesets.yaml -├── paths/ -│ ├── authentication.yaml -│ ├── demo.yaml -│ ├── edge-api.yaml -│ ├── master-data.yaml -│ ├── orders.yaml -│ ├── organization.yaml -│ ├── patient-visits.yaml -│ ├── patients.yaml -│ ├── results.yaml -│ ├── specimen.yaml -│ ├── tests.yaml -│ └── valuesets.yaml -└── bundle-api-docs.py # Bundler script -``` - -## Architecture - -### Server-Side Resolution - -The application uses a CodeIgniter 4 controller (`app/Controllers/OpenApiDocs.php`) that: -1. Loads `public/api-docs.yaml` (base spec with schemas) -2. Scans `public/paths/*.yaml` files -3. Merges all paths into the base spec -4. Outputs complete YAML response - -### Benefits -- ✅ **No bundling step** - Files merged at runtime -- ✅ **Immediate updates** - Changes reflect immediately -- ✅ **Modular structure** - Separate files by domain -- ✅ **CI4 compatible** - Works with CodeIgniter 4 -- ✅ **Nginx ready** - Can migrate to Nginx later -- ✅ **Cacheable** - Can add caching for production - -## Usage - -### For Development - -Edit files directly: -- **Paths:** `public/paths/*.yaml` -- **Schemas:** `public/components/schemas/*.yaml` - -### For Production/Swagger UI - -**Endpoint:** `http://localhost/clqms01/api-docs` - -The endpoint merges all files server-side and returns a complete OpenAPI specification that Swagger UI can consume. - -## Caching (Optional) - -For production, you can add caching to the `OpenApiDocs` controller: - -```php -// In OpenApiDocs::index() -$cacheKey = 'openapi_spec_' . filemtime(FCPATH . 'api-docs.yaml'); -if ($cached = cache()->get($cacheKey)) { - return $this->response->setBody($cached); -} - -// ... build spec ... - -// Cache for 5 minutes -cache()->save($cacheKey, $yaml, 300); -``` - -## Configuration Update - -Update your application configuration to use the bundled file: - -**PHP (CodeIgniter):** -```php -// Already updated in app/Views/swagger.php: -url: "" -``` - -**JavaScript/Node:** -```javascript -// Change from: -const spec = await fetch('/api-docs.yaml'); - -// To: -const spec = await fetch('/api-docs.bundled.yaml'); -``` - -## Benefits - -1. **Modular**: Each domain has its own file -2. **Maintainable**: Easier to find and update specific endpoints -3. **Team-friendly**: Multiple developers can work on different files -4. **Schema Reuse**: Schemas defined once, referenced everywhere -5. **Better Versioning**: Individual domains can be versioned separately - -## Migration Notes - -- **From bundled to server-side:** Already done! The system now uses server-side resolution. -- **Nginx migration:** When ready to migrate to Nginx, the approach remains the same (CI4 handles the merging). -- **Back to bundling:** If needed, the bundler script is still available: `python bundle-api-docs.py` - -## Troubleshooting - -### Schema Resolution Errors - -If you see errors like "Could not resolve reference", ensure: -1. Schema files exist in `components/schemas/` -2. References use correct relative paths (e.g., `./components/schemas/patient.yaml#/Patient`) -3. You're using the bundled file (`api-docs.bundled.yaml`) for OpenAPI tools - -### Path Resolution Errors - -OpenAPI 3.0 doesn't support external file references for paths. Always use the bundled version for serving the documentation. - -## Migration Notes - -- The original `api-docs.yaml` is preserved with schema references only -- All paths have been moved to individual files in `paths/` directory -- A bundler script merges everything into `api-docs.bundled.yaml` -- Update your application to serve `api-docs.bundled.yaml` instead diff --git a/public/bundle-api-docs.php b/public/bundle-api-docs.php deleted file mode 100644 index 68c72d9..0000000 --- a/public/bundle-api-docs.php +++ /dev/null @@ -1,55 +0,0 @@ - - - - - - - Elements in HTML - - - - - - - - - - \ No newline at end of file diff --git a/public/swagger/index.html b/public/swagger/index.html new file mode 100644 index 0000000..0cf27aa --- /dev/null +++ b/public/swagger/index.html @@ -0,0 +1,235 @@ + + + + + + CLQMS API Documentation + + + + + + + + +
+ + + + +