---
name: OpenAPI Sync Subagent
overview: Create a Cursor skill and optional command that instructs an agent to generate/update openapi.yaml and openapi-wss.yaml from src/*, update README references, and append CHANGELOG entries.
todos: []
isProject: false
---

# OpenAPI Sync Subagent Plan

## Context

Athena maintains two OpenAPI specs at the repo root:

- [openapi.yaml](openapi.yaml) - REST API (~1900 lines, manually maintained)
- [openapi-wss.yaml](openapi-wss.yaml) - WebSocket gateway (~87 lines)

Both are bundled at compile time via `include_str!` in [src/api/mod.rs](src/api/mod.rs). The project uses Actix Web with `#[get]`, `#[post]`, `#[put]`, `#[delete]` macros; there is no utoipa or code-generated spec.

## Deliverables

### 1. Skill: `.cursor/skills/openapi-sync/SKILL.md`

A project skill that teaches the agent how to perform the full sync workflow. The skill will:

- **Trigger**: When the user asks to "update OpenAPI specs", "sync OpenAPI", "regenerate openapi.yaml", or similar
- **Scope**: REST API in `src/api/`_, WSS API in `src/wss/`_
- **Output**: Updated `openapi.yaml`, `openapi-wss.yaml`, README references, CHANGELOG entry

### 2. Optional Command: `.cursor/commands/openapi-sync.md`

A Cursor command that invokes the workflow with a single prompt, for quick "run the sync" usage.

---

## Workflow (Skill Instructions)

### Phase 1: Introspect REST API

1. **Grep for route macros** in `src/api/**/*.rs`:

- `#[get("...")]`, `#[post("...")]`, `#[put("...")]`, `#[delete("...")]`
- Also check `main.rs` for `.service(...)` and `.configure(...)` to capture all registered routes

1. **Build route list** - Extract path and HTTP method from each handler. Key files:

- [src/api/health.rs](src/api/health.rs): `/`, `/ping`, `/health/cluster`
- [src/api/gateway/fetch/mod.rs](src/api/gateway/fetch/mod.rs): `/gateway/data`, `/gateway/fetch`, `/gateway/update`, `/data`
- [src/api/gateway/insert/mod.rs](src/api/gateway/insert/mod.rs): `/gateway/insert`
- [src/api/gateway/update/mod.rs](src/api/gateway/update/mod.rs): `/gateway/insert` (PUT)
- [src/api/gateway/delete/mod.rs](src/api/gateway/delete/mod.rs): `/gateway/delete`
- [src/api/gateway/query/mod.rs](src/api/gateway/query/mod.rs): `/gateway/query`
- [src/api/gateway/postgrest/mod.rs](src/api/gateway/postgrest/mod.rs): `/rest/v1/{table}`
- [src/api/admin/mod.rs](src/api/admin/mod.rs): `/admin/`
- [src/api/management/mod.rs](src/api/management/mod.rs): `/management/`
- [src/api/schema.rs](src/api/schema.rs): `/schema/`, `/clients`
- [src/api/registry/mod.rs](src/api/registry/mod.rs): `/registry`, `/registry/{id}`
- [src/api/pipelines/mod.rs](src/api/pipelines/mod.rs): `/pipelines`
- [src/api/query/sql/mod.rs](src/api/query/sql/mod.rs): `/query/sql`
- [src/api/supabase.rs](src/api/supabase.rs): `/api/v2/supabase/ssl_enforcement`
- [src/api/metrics.rs](src/api/metrics.rs): `/metrics`
- [src/api/mod.rs](src/api/mod.rs): `/router/registry`, `/openapi.yaml`, `/openapi-wss.yaml`, `/docs`
- [src/wss/mod.rs](src/wss/mod.rs): `/wss/info`

1. **Diff against openapi.yaml** - For each path in code:

- If missing in spec: add minimal path entry (method, summary, 200 response)
- If present: preserve existing docs; only fix path/method mismatches
- Preserve `info.version` from `Cargo.toml` (or use [scripts/sync_version.py](scripts/sync_version.py) convention)

### Phase 2: Introspect WSS API

1. **Inspect** [src/wss/mod.rs](src/wss/mod.rs):

- `GatewayWsRequest` and `GatewayWsResponse` structs
- `/wss/info` GET handler
- `/wss/gateway` - documented as WebSocket upgrade path (no handler in Actix; CDC uses Axum at `/ws`)

1. **Update openapi-wss.yaml**:

- Ensure `paths` match: `/wss/gateway`, `/wss/info`
- Sync `GatewayWsRequest`/`GatewayWsResponse` schemas with Rust struct fields
- Align `info.version` with Cargo.toml or keep WSS-specific version if desired

### Phase 3: Update README References

Search for `openapi.yaml` and `openapi-wss.yaml` in all `README.md` files and ensure:

- Paths and descriptions are accurate
- No broken or outdated references

Current references in [README.md](README.md): lines 29, 34, 272, 321, 513, 515.

### Phase 4: Append CHANGELOG

1. Read version from `Cargo.toml` (e.g. `1.2.0`)
2. Insert new section at top (after `# Changelog`), following existing format:

```markdown
## [1.2.0](https://github.com/xylex-group/athena/compare/v1.1.0...v1.2.0) (YYYY-MM-DD)

### Documentation

- Update openapi.yaml to reflect current REST API routes
- Update openapi-wss.yaml to reflect WebSocket gateway contract
- Sync README references to OpenAPI specs
```

Use today's date. Adjust compare URL to previous version if known.

---

## Implementation Notes

### Generation Strategy

**Recommended: Agent-based introspection** (no new dependencies). The agent greps routes, diffs against YAML, and applies targeted edits. Preserves existing detailed schemas and parameters.

**Alternative (future): utoipa** - Add `utoipa` + `utoipa-actix-web`, annotate handlers with `#[utoipa::path]`, generate YAML at build. More invasive; consider only if spec drift becomes a recurring problem.

### Version Sync

[scripts/sync_version.py](scripts/sync_version.py) syncs Cargo.toml, README, and openapi.yaml. It does **not** touch openapi-wss.yaml. The skill can optionally extend sync_version.py to include openapi-wss.yaml, or the agent can update it manually during the workflow.

### Validation

After edits, run:

- `cargo build` - ensures `include_str!` still works
- `cargo test --test openapi` - [tests/openapi.rs](tests/openapi.rs) asserts embedded specs match files

---

## File Structure

```
.cursor/
├── skills/
│   └── openapi-sync/
│       └── SKILL.md          # Main skill instructions
└── commands/
    └── openapi-sync.md       # Optional: single-prompt invocation
```

---

## Skill SKILL.md Outline

```markdown
---
name: openapi-sync
description: Generates or updates openapi.yaml and openapi-wss.yaml from src/* Rust API, updates README references, and appends CHANGELOG. Use when syncing OpenAPI specs, documenting API changes, or after adding/modifying REST or WSS routes.
---

# OpenAPI Sync

## Workflow

1. Introspect src/api/** and src/wss/** for route macros and handlers
2. Update openapi.yaml: add missing paths, preserve existing docs
3. Update openapi-wss.yaml: sync with GatewayWsRequest/Response and /wss/\* paths
4. Update README.md references (grep for openapi\*.yaml)
5. Append CHANGELOG.md with version and changes

## Route Discovery

Grep: #\[get\(|#\[post\(|#\[put\(|#\[delete\(
Check main.rs for .service() and .configure() registration.

## CHANGELOG Format

Insert after # Changelog. Use Cargo.toml version. Date: YYYY-MM-DD.
```

---

## Mermaid: Workflow

```mermaid
flowchart TD
    Start[User invokes openapi-sync] --> Introspect[Introspect src/api and src/wss]
    Introspect --> DiffREST[Diff 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[Append CHANGELOG entry]
    Changelog --> Validate[cargo build and cargo test]
```
