koi_swagger_parser/doc/ARCHITECTURE.md

Architecture

English | Chinese (Simplified)

The generation pipeline is deliberately split into stages:

configuration
  -> source loader
  -> external/local $ref resolver
  -> multi-source merger
  -> validation + parser
  -> transport/schema IR
  -> preset + Dart renderer
  -> manifest lifecycle
  -> fix / format / build_runner

The main invariant is that loading produces a self-contained document with traceable dependencies; the parser represents OpenAPI semantics; the renderer does not reinterpret the specification; and the lifecycle manages only files declared in its manifest.

Configuration

lib/src/config/config.dart:

• discovers koi_swagger_parser.yaml and compatible generator_config.yaml names;
• resolves source and output paths against the configuration directory;
• chooses the host-project command directory from --cwd or the explicit configuration directory;
• validates YAML scalar types before casting;
• parses enum, naming, type/import mappings, and filters;
• validates unsupported combinations, mapping collisions, regular expressions, and enum mappings;
• supports migration from the legacy base_result_import setting.

Unknown keys produce warnings. Invalid types and incomplete combinations produce errors. See Configuration.

Loader, resolver, and merger

For each root source, OpenApiReferenceResolver:

1. normalizes a local file, file URL, or HTTP(S) source;
2. caches each loaded document;
3. resolves local, relative, and remote $ref values;
4. bundles external components into the root document;
5. assigns deterministic names to component conflicts;
6. records dependencies and diagnoses unsupported cross-document cycles.

OpenApiDocumentMerger then merges roots in configuration order:

• a duplicate operation method/path is an error;
• components with the same name but different content are renamed deterministically, and references from that source are rewritten;
• later inputs never silently overwrite conflicts;
• version, info, and path-parameter conflicts are reported.

The parser should receive only root-document JSON Pointers. A remaining external reference is treated as a resolver error.

Validation and parsing

OpenApiDocumentParser handles:

• OpenAPI 3.0/3.1 version and core structure checks;
• operation, path, tag, and model filters;
• parameter location, style, explode, allowReserved, and content;
• request media types and response status, content, and headers;
• servers, security schemes, and security requirements;
• required, nullable, read-only/write-only, and additionalProperties semantics;
• enum configuration/vendor-extension precedence;
• allOf, discriminated unions, and supported generic unions;
• custom mappings and Dart name collisions.

A structure that cannot be rendered with reliable wire semantics must not silently become dynamic. A safe but lossy continuation produces a warning; for example, different successful JSON body types may converge on Object?. A media type without a supported decoder, such as XML or Protobuf, produces an error.

Intermediate representation

lib/src/ir/ir.dart is the parser/renderer contract. Its main nodes include:

• ApiOperation: method, path, tag, version, server, and security data;
• ApiParameter: Dart/wire name, location, style, explode, and allowReserved;
• ApiRequestBody: JSON, multipart, form-urlencoded, and binary requests;
• ApiResponse: status/default, body kind/type, content type, and headers;
• ModelSpec: object, enum, and union models with usage category and extras;
• ModelField: required/nullability/read-write flags and constraints;
• DartType: named, list, map, object, dynamic, and void type graphs.

Models are grouped as request, result, shared, or enum models. A component with read-only/write-only properties can be projected into request and response variants so that read-only values are not required in requests and write-only secrets are not exposed in responses.

A generic oneOf requires exactly one decoder match. A generic anyOf retains the raw value and all matching cases. Object branches are prefiltered by required keys and enum constraints before decoding.

Preset and renderer

The current koi_flutter preset targets Dio, Retrofit, Freezed, and json_serializable.

The renderer:

• uses Retrofit annotations for parameter forms Retrofit can represent;
• emits a typed public adapter and private Retrofit delegate when a supported style, cookie, or allowReserved combination needs custom serialization;
• renders Freezed object, enum, and union models;
• renders custom root-map read/write helpers for properties plus additionalProperties;
• collects model dependencies and external type imports;
• groups API files by version and tag and emits client/index files.

The renderer does not load references or decide whether an OpenAPI structure is valid.

Generation lifecycle

Before writing, GenerationLifecycle calculates:

• the canonical merged-spec SHA-256;
• the normalized configuration SHA-256;
• each rendered path and content SHA-256.

The manifest records its schema/generator version, source roots, dependencies, and the actual hash of each primary generated file. Writes use an operating system exclusive lock and same-directory temporary-file rename.

Safety invariants:

1. Renderer output must stay inside the configured API/model roots.
2. A stale candidate must come from the previous manifest.
3. Its path must still be inside the current managed roots.
4. Its current hash must equal the previous manifest hash before deletion.
5. A corrupt or unknown-version manifest is never trusted for deletion.
6. A failed fix, format, or build step does not write a success manifest.
7. Watch mode starts after the generation lock is released.

build_runner owns .g.dart and .freezed.dart files; they are not included in this generator's stale-file manifest.

Response wrappers

The parser does not hard-code BaseResult:

• passthrough returns the OpenAPI response schema;
• external_generic detects configured success envelopes and returns ExternalWrapper<Inner>.

A default response remains an error response. response_mode: http_response retains Dio status and headers. Error response models remain in the IR and generated model set.

Extension boundaries

The IR/preset/renderer split leaves room for a versioned renderer interface, template overrides, semantic-diff tooling, and optional runtime adapters. Those are design directions, not features of the current public release. The current implementation boundaries are documented in Compatibility.

Additional ecosystem comparisons are kept as internal project research and are not part of the published package.