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:

```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: "<?= base_url('api-docs.bundled.yaml') ?>"
```

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