# OpenAPI Cleanup Plan

This branch exists to replace the current generated API schema layer.

## Current problem

`comfy/api/components/schema/*` was generated by `openapi-json-schema-generator`.
The generated validators are too strict for Comfy workflow payloads. In
particular, `PromptNode.inputs.additionalProperties` was generated as a
`oneOf` over scalar values and link tuples. Real workflow input values are
looser than that: custom nodes may use `null`, nested objects, arrays, scalar
values, or link tuples. Because the generated validator enforces exclusive
`oneOf` matching, it rejects valid prompt payloads before the execution layer
can validate node semantics.

The short-term fix on this branch changes prompt input validation to `anyOf`
and includes `null`, object, and array payloads.

## Spec source

`openapi.yaml` at the repository root is the canonical spec. It contains the
fork's broader REST surface and the upstream-compatible ComfyUI routes. The old
package-local OpenAPI file under `comfy/api/` has been removed; do not recreate
package-local OpenAPI specs. When upstream changes its API spec, merge the
relevant route and schema fixes into root `openapi.yaml`.

The canonical spec must preserve both surfaces:

- upstream-compatible ComfyUI routes, including the unprefixed vanilla paths
  and `/api` aliases exposed by the server;
- fork-only REST APIs such as assets, workflows, hub, auth, billing,
  workspace, secrets, tasks, jobs, and internal operational endpoints.

## Generator direction

Do not continue expanding the current `openapi-json-schema-generator` output.
Use a Pydantic v2 based generator for Python models instead. The repo already
depends on Pydantic v2 and has hand-written Pydantic API models under
`comfy/app/assets/api/`, so this matches the local runtime stack better than
the current custom generated schema runtime.

Candidate tool: `datamodel-code-generator`, configured for:

- OpenAPI 3 input.
- Pydantic v2 output.
- Python 3.10 target, matching the package's supported runtime floor.
- Strict enough typed models for stable REST request/response models.
- Permissive `JsonValue`/`dict[str, Any]` shapes for workflow graphs,
  prompt inputs, queue metadata, history payloads, and custom-node surfaces.

## Migration steps

1. Maintain root `openapi.yaml` as the only canonical merged OpenAPI document.
2. Keep workflow graph schemas intentionally loose at API boundaries.
3. Generate Pydantic v2 models into `comfy/api/generated/models.py`, separate
   from the prompt compatibility shims.
4. Port server/client call sites from `Prompt.validate()` style validation to
   Pydantic `model_validate()` only where validation is useful.
5. Keep only tiny compatibility shims for current imports such as
   `Prompt.validate`, `PromptDict`, `PromptRequest`, and `ApiValueError`.
6. Add round-trip tests for bundled workflows, UI-converted workflows, queue
   payloads, history payloads, and fork-only REST endpoints.
