koi_swagger_parser/doc/internal/COMMUNITY_COMPARISON.md

# Comparison with mature open-source generators

Internal research reviewed on 2026-07-31 against official documentation:

- [OpenAPI Generator dart-dio](https://openapi-generator.tech/docs/generators/dart-dio/)
- [OpenAPI Generator customization](https://openapi-generator.tech/docs/customization/)
- [Swagger Codegen](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/about/)
- [Swagger Codegen generator customization](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generators/)
- [Microsoft Kiota](https://learn.microsoft.com/en-us/openapi/kiota/)
- [Kiota design](https://learn.microsoft.com/en-us/openapi/kiota/design)
- [Kiota authentication](https://learn.microsoft.com/en-us/openapi/kiota/authentication)
- [Kiota backing store](https://learn.microsoft.com/en-us/openapi/kiota/backing-store)

This document is a planning comparison, not a public compatibility promise.
See [Compatibility](../COMPATIBILITY.md) for verified behavior.

## Positioning

| Dimension | Mature community tools | `koi_swagger_parser` |
|---|---|---|
| Output scope | Many client languages, server stubs, and documentation | Dart/Flutter code inside an existing Retrofit + Freezed project |
| Specification parsing | Mature OpenAPI models/validation and large corpora | Purpose-built loader/parser/IR for a documented OpenAPI 3.0/3.1 subset |
| Extension model | Templates, custom generators, language backends, plugins | Separated preset/IR/renderer, but no stable external renderer interface |
| Naming/type reuse | Model/property/parameter/operation/type/import mappings | Comparable mapping categories with early collision checks |
| HTTP runtime | Kiota request adapter, authentication, and middleware abstractions | Dio/Retrofit, with generated adapters for supported wire styles |
| Authentication | Generated schemes or provider abstractions | Server/security metadata; credentials supplied by host Dio code |
| Model state | Optional backing stores and explicit presence tracking | Immutable Freezed models; absent/null validation without dirty tracking |
| Deliverable | Can scaffold a standalone SDK package | Generates APIs/models into an existing package |
| Lifecycle | Established CLI/plugin/build-system integrations | Local manifest, locking, hashes, safe stale cleanup, and build_runner |

## Current differentiators

The official OpenAPI Generator dart-dio feature table marks multi-server,
parameterized-server, and parameter-styling support as unavailable. Within its
documented subset, `koi_swagger_parser` implements root/path/operation server
variables and path/query/header/cookie style/explode handling, using a typed
adapter when Retrofit annotations cannot express the wire format.

Other project-specific strengths include:

- OpenAPI 3.1 nullable versus required/absent behavior for
  json_serializable;
- root `properties` plus `additionalProperties` round trips;
- directional read-only/write-only models;
- discriminator and structural union matching;
- external generic Koi response envelopes;
- multiple enum vendor extensions plus configuration precedence;
- hash-protected cleanup limited to generator-owned files;
- generated-package build_runner/analyze/test verification.

These are useful differentiators for Koi-style Dart clients; they do not imply
broader specification coverage than mature general-purpose generators.

## Gaps compared with mature ecosystems

### Specification and JSON Schema breadth

The implementation is not a complete JSON Schema 2020-12 validator. Broader
third-party document coverage would require selected `$defs`/JSON Pointer
cases, conditional and unevaluated schemas, richer constraint interaction,
larger official/community corpora, fuzz/property tests, and resource/performance
benchmarks.

### Renderer and template extensibility

OpenAPI Generator and Swagger Codegen allow template replacement and custom
language generators. A comparable extension boundary would require a
versioned IR contract, renderer interface, template overrides, alternative
Dart stacks, layout/header hooks, and generator compatibility checks.

### Runtime abstraction

Kiota separates requests, serialization, authentication, and transport. A
future Dio-oriented optional runtime layer could provide typed authentication
providers, retry/telemetry hooks, error mapping, pagination/long-running
operation helpers, download progress, and presence tracking for PATCH.

### Standalone SDK delivery

Generating a publishable SDK rather than files inside an application would
also require package scaffolding, dependency-version policy, generated
documentation/examples, semantic breaking-change reports, runtime/generator
version pinning, and reproducible release archives.

## Explicitly deferred scope

- Swagger/OpenAPI 2.0.
- Callbacks, webhooks, and Link Object execution.
- XML, Protobuf, and arbitrary codecs.
- Complete OAuth login and mutual-TLS runtime flows.
- Server stubs and mock servers.
- Non-Dart code generation.

These do not block the current Koi/FastAPI client goal, but encountering them
must produce documented diagnostics rather than plausible-looking output.

## Suggested priority

1. Expand fixture/fuzz coverage and add large-document performance benchmarks.
2. Version the IR and define a renderer/template extension boundary.
3. Add semantic diff and CI-check modes.
4. Add optional authentication/error/middleware hooks.
5. Add PATCH presence and dirty tracking if demanded by consumer APIs.
6. Expand the JSON Schema subset only for concrete production fixtures.
7. Add Swagger 2, XML, or callbacks only when a confirmed consumer requires
   them.

This order preserves the focused Dart/Koi value while adopting engineering
features with demonstrated reuse value.