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.
This commit is contained in:
mr.koi
@@ -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.
|
||||
@@ -0,0 +1,75 @@
|
||||
# Product goal
|
||||
|
||||
This is an internal planning record for the 0.2.0 development milestone.
|
||||
User-facing support commitments are defined by
|
||||
[Compatibility](../COMPATIBILITY.md).
|
||||
|
||||
## Objective
|
||||
|
||||
Evolve `koi_swagger_parser` from a Koi/FastAPI happy-path script into a
|
||||
reliable, diagnosable, and extensible OpenAPI 3.0/3.1 Dart/Flutter client
|
||||
generator. Preserve the loader -> resolver/merger -> parser/IR ->
|
||||
preset/renderer -> lifecycle architecture and the Koi-oriented
|
||||
Retrofit/Freezed output style.
|
||||
|
||||
## Definition of done
|
||||
|
||||
1. **Diagnostics**: versions, invalid structures, unsupported constructs,
|
||||
conflicts, and degradations have stable codes and source/location context.
|
||||
2. **References**: local, relative-file, and remote references cover component
|
||||
groups with caching, cycle detection, multi-source conflict handling, and
|
||||
dependency tracking.
|
||||
3. **Mappings**: enum configuration and vendor extensions have deterministic
|
||||
precedence and unknown fallback; model, property, parameter, operation,
|
||||
schema, type, and import mappings are validated.
|
||||
4. **HTTP**: path/query/header/cookie serialization and supported
|
||||
style/explode/allowReserved combinations are correct; JSON, multipart,
|
||||
form-urlencoded, text, and binary transfers work.
|
||||
5. **Responses**: multiple 2xx, 204, `2XX`, `default`, error models, headers,
|
||||
raw `HttpResponse`, and byte/stream output are represented.
|
||||
6. **Schemas**: required/nullable/absent, read-only/write-only,
|
||||
additional-properties, composition/union, custom-scalar, and constraint
|
||||
metadata enter the IR and output within documented boundaries.
|
||||
7. **Client metadata**: servers/base URLs and security requirements are
|
||||
available while remaining compatible with host Dio interceptors.
|
||||
8. **Lifecycle**: configuration is effective; manifest locking/hashing,
|
||||
unchanged skips, safe stale cleanup, filters, and build_runner integration
|
||||
are complete.
|
||||
9. **Quality gate**: layered tests, conflict/error cases, OpenAPI 3.0/3.1
|
||||
fixtures, golden output, and a temporary generated-package
|
||||
build/analyze/test verification pass.
|
||||
10. **Documentation**: README, configuration, compatibility, diagnostics, and
|
||||
migration documentation match the implementation in English and
|
||||
Simplified Chinese.
|
||||
|
||||
## Non-goals for this milestone
|
||||
|
||||
- Swagger/OpenAPI 2.0.
|
||||
- Callback, webhook, and Link Object call generation.
|
||||
- XML, Protobuf, and arbitrary codecs.
|
||||
- Complete JSON Schema 2020-12.
|
||||
- Server stubs, mock servers, and non-Dart output.
|
||||
- Independent generated-SDK publishing.
|
||||
|
||||
Non-goals must still produce an explicit warning or error when encountered.
|
||||
|
||||
## Evidence
|
||||
|
||||
```bash
|
||||
dart format .
|
||||
dart analyze
|
||||
dart test
|
||||
dart run tool/verify_generated_package.dart
|
||||
```
|
||||
|
||||
The end-to-end verifier must let the generator invoke build_runner and then
|
||||
run analysis and runtime tests in the generated package. String-fragment checks
|
||||
alone are insufficient.
|
||||
|
||||
## Next horizon
|
||||
|
||||
Potential follow-up work includes a larger fixture/fuzz/performance corpus,
|
||||
versioned IR and renderer interfaces, semantic-diff/CI mode, optional
|
||||
authentication/error/middleware adapters, and PATCH presence tracking.
|
||||
JSON Schema or Swagger 2 scope should expand only in response to concrete
|
||||
consumer fixtures.
|
||||
Reference in New Issue
Block a user