# CRM API Docs

This directory contains the generated OpenAPI contract for `crm/www/php`.

## Generate

Run:

```bash
php /home/crm/www/api-docs/generate_openapi.php
```

That updates:

- `openapi.json`: machine-readable API contract
- `undocumented-routes.json`: endpoints that still need `@fm-doc`
- `index.html`: static Redoc renderer for the generated contract

## Source Format

Document endpoints inline with a `@fm-doc` JSON block near the top of `php/<Object>/<action>.php`.

Supported top-level fields:

- `function`: route function name, for example `Customer_get`
- `operationId`: optional explicit OpenAPI operation id
- `summary`
- `description`
- `tags`: array of tag names
- `auth`: array of auth modes from `session_cookie`, `api_key_signature`, `app_session_signature`
- `params`: compact request-field list for form-encoded requests
- `request`: optional full request schema override
- `responses`: optional explicit OpenAPI response map
- `examples`: request/response examples and CRM-specific row maps
- `deprecated`: optional boolean

If `responses` is omitted, the generator derives a basic `200` response from `examples.response_success` and always emits a shared error response.

## Notes

- The API is documented as `POST /a/Object_action` because the dispatcher reads from `$_REQUEST`.
- Existing callers may still use GET if the endpoint supports it.
- Packed-array responses should stay documented as-is. Use `examples.response_row_index_map` to explain row indexes.