Release 0.2.0

Complete OpenAPI 3.0/3.1 generation, diagnostics, lifecycle safety, enum and naming mappings, bilingual documentation, examples, and pub.dev release validation.

doc/internal/COMMUNITY_COMPARISON.md

@@ -0,0 +1,109 @@
+# 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.