# Standalone OpenAPI YAML (`openapi.yml`)

Repository root file [`openapi.yml`](../openapi.yml) is the OpenAPI 3.1
spec used by `/docs` (enriched examples). Keep it in sync with the running app
after route/schema changes.

**Regenerate (from repo root):**

```bash
python3 -c "
from pathlib import Path
import json, yaml
from app.main import app
from app.openapi_enrich import enrich_openapi_examples
app.openapi_schema = None
schema = enrich_openapi_examples(app.openapi())
Path('openapi.yml').write_text(yaml.safe_dump(schema, sort_keys=False, allow_unicode=True))
Path('docs/swagger/ALL_APIS.openapi.yaml').write_text(yaml.safe_dump(schema, sort_keys=False, allow_unicode=True))
Path('docs/swagger/ALL_APIS.openapi.json').write_text(json.dumps(schema, indent=2)+'\n')
print('paths', len(schema['paths']))
"
```

Also mirrored under [`docs/swagger/ALL_APIS.openapi.yaml`](./swagger/ALL_APIS.openapi.yaml).

Job matching contract (Platform DB → `job_catalog`): [`JOB_MATCHING.md`](./JOB_MATCHING.md).

Resume inputs (file / text / `candidate_id`): [`RESUME_INPUT.md`](./RESUME_INPUT.md).

## Swagger Editor

1. Open https://editor.swagger.io/
2. **File → Import file** (or paste) `openapi.yml`
3. Click **Authorize** → enter staging `INTERNAL_API_TOKEN` as `X-Internal-Token`
4. Use **Try it out** on any operation

Requests are sent to the staging server defined under `servers`.

## Swagger UI (self-hosted / Docker)

Point Swagger UI at the YAML (or a hosted copy) and set the API server to staging:

```text
http://95.111.228.198:8001
```

Example (Docker):

```bash
docker run -p 8080:8080 \
  -e SWAGGER_JSON=/openapi.yml \
  -v "$PWD/openapi.yml:/openapi.yml:ro" \
  swaggerapi/swagger-ui
```

Then open http://localhost:8080 and Authorize with `X-Internal-Token`.

## Important

- Write operations (**POST** / **PATCH**) may create or change data on **staging**.
- Dummy request examples are fictional (e.g. Johannes Wachsmuth) and illustrative.
- Media endpoints (face/ID/video/TTS/audio) need real files/frames and often GPU/CV deps.
- Do not put real tokens or PII into `openapi.yml`.

## Regenerate from local FastAPI (preferred)

```bash
source venv/bin/activate
python3 -c "
from pathlib import Path
import json, yaml
from app.main import app
schema = app.openapi()
schema['servers'] = [
  {'url': 'http://localhost:8000', 'description': 'Local AI Gateway'},
]
Path('openapi.yml').write_text(yaml.dump(schema, sort_keys=False, allow_unicode=True))
Path('docs/swagger/ALL_APIS.openapi.json').write_text(json.dumps(schema, indent=2)+'\n')
Path('docs/swagger/ALL_APIS.openapi.yaml').write_text(yaml.dump(schema, sort_keys=False, allow_unicode=True))
print('updated')
"
```

Create Job / JD path: `POST /api/v1/jobs?action=draft|rewrite|validate|publish`
(body schemas: JobDraftBody / JobRewriteBody / JobValidateBody / JobPublishBody).
