clqms-be/public/API_DOCS_README.md

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:

// 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):

// Already updated in app/Views/swagger.php:
url: "<?= base_url('api-docs.bundled.yaml') ?>"

JavaScript/Node:

// 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