---
name: openapi-sync
description: Generate or refresh `openapi.yaml` and `openapi-wss.yaml` from the Rust HTTP/WSS routes, update README references, and append the resulting work to `CHANGELOG.md`. Use when a route changes, a new handler lands, or the WebSocket contract shifts.
---

# OpenAPI Sync Skill

## When to run

- The user asks to regenerate or sync the OpenAPI specs (HTTP or WSS) with the current Rust HTTP/WSS handlers.
- New REST routes, query parameters, or headers land in `src/api/**/*.rs`.
- The WebSocket contract updates in `src/wss/*.rs` or any new WSS handler is introduced.
- Documentation (README/CHANGELOG) should reference the refreshed specs.

## Workflow

1. Gather every registered HTTP route method/path from `src/api/**/*.rs` and `src/main.rs` (`.service`, `.configure`, `.route`). Pay attention to `#[get(...)]`, `#[post(...)]`, `#[put(...)]`, `#[delete(...)]`.
2. Diff that list against `openapi.yaml`. Only materialise the missing paths/methods; leave the existing descriptions/schemas untouched unless they are incorrect.
3. Inspect `src/wss/mod.rs` (and any other WSS entrypoints) to capture `/wss/info`, the advertised `/wss/gateway` upgrade, and the `GatewayWsRequest`/`GatewayWsResponse` fields. Keep `openapi-wss.yaml` aligned with that contract.
4. Ensure every README that mentions the specs (`README.md` at repo root currently references `openapi.yaml`/`openapi-wss.yaml` in several sections) describes the freshly synced files.
5. Prepend a `CHANGELOG.md` entry under the current version with a Documentation section describing the OpenAPI sync.
6. Validate by running `cargo build` and `cargo test --test openapi`; the latter asserts `tests/openapi.rs` matches the embedded files.

## REST spec guidance

- Reference these files for the major route groups:
  - `src/api/health.rs`: `/`, `/ping`, `/health/cluster`.
  - `src/api/gateway/{fetch,insert,update,delete,query}.rs`: `/gateway/*`, `/data`, `/query/sql`, `/rest/v1/{table}`.
  - `src/api/admin/mod.rs`: `/admin/*`.
  - `src/api/management/mod.rs`: `/management/*`.
  - `src/api/schema.rs`: `/schema/clients`, `/schema/tables`, `/schema/columns`, `/schema/migrations`, `/clients`.
  - `src/api/registry/mod.rs`: `/registry`, `/registry/{api_registry_id}`.
  - `src/api/pipelines/mod.rs`: `/pipelines`.
  - `src/api/supabase.rs`: `/api/v2/supabase/ssl_enforcement`.
  - `src/api/metrics.rs`: `/metrics`.
  - `src/api/mod.rs`: `/router/registry`, `/openapi.yaml`, `/openapi-wss.yaml`, `/docs`.
  - `src/main.rs`: list of `.service` and `.configure` calls ensures no handler is omitted.

- When adding a missing path:
  - Include a brief `summary`, `description`, and `200` response stub matching the standard `{ status, message, data }` envelope unless the handler already documents a different payload.
  - Reuse shared schema references from existing `components/schemas` whenever possible.
  - Keep `info.version` aligned with `Cargo.toml` (use `scripts/sync_version.py` as a reference if necessary).

- If a handler has query/body payloads already documented (for example, the gateway fetch payload), preserve or refine those definitions rather than overwriting them entirely.

## WSS spec guidance

- Confirm `/wss/info` still mirrors `gateway_wss_info`.
- The contract for `/wss/gateway` should match `GatewayWsRequest`/`GatewayWsResponse`. Check:
  - `action`, `client_name`, `path`, optional `method`, and the `headers`, `query`, `body` bags.
  - Response fields `status`, `message`, `data`, and optional `request_id`.
- Update `components/schemas` to match the latest struct fields. When adding properties, mention whether they are required.
- Keep `info.version` in `openapi-wss.yaml` consistent with the crate release or set a WSS-specific number if you already track it separately. Document the choice in the README.

## README & CHANGELOG updates

- Search every README (start with the root `README.md`) for `openapi.yaml`/`openapi-wss.yaml` references and rewrite them to describe the regenerated specs and where to download them (`GET /openapi.yaml`, `GET /openapi-wss.yaml` are already served).
- Prepend a changelog entry matching the existing style:

```markdown
## [<version>](https://github.com/xylex-group/athena/compare/<previous>...<version>) (YYYY-MM-DD)

### Documentation

- Sync `openapi.yaml` with the current Rust REST routes.
- Sync `openapi-wss.yaml` with the WebSocket contract.
- Note the spec updates in `README.md` references.
```

- Derive `<version>` from `Cargo.toml`. Use `scripts/sync_version.py` if additional version bumps are needed.

## Verification

1. `cargo build`.
2. `cargo test --test openapi`.
3. Manual spot-check: `curl -s https://localhost:4052/openapi.yaml | head` (or run the same against the running server) to ensure the spec served matches the file.

## Workflow diagram

```mermaid
flowchart TD
  Start[User requests openapi-sync] --> Introspect[Introspect src/api and src/wss]
  Introspect --> DiffREST[Diff REST routes vs openapi.yaml]
  DiffREST --> UpdateREST[Update openapi.yaml]
  Introspect --> DiffWSS[Diff WSS vs openapi-wss.yaml]
  DiffWSS --> UpdateWSS[Update openapi-wss.yaml]
  UpdateREST --> README[Update README references]
  UpdateWSS --> README
  README --> Changelog[Prepend CHANGELOG entry]
  Changelog --> Validate[Run cargo build & cargo test --test openapi]
```
