mr.koi
454e6c51d7
Complete OpenAPI 3.0/3.1 generation, diagnostics, lifecycle safety, enum and naming mappings, bilingual documentation, examples, and pub.dev release validation.
3.1 KiB
Product goal
This is an internal planning record for the 0.2.0 development milestone. User-facing support commitments are defined by Compatibility.
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
- Diagnostics: versions, invalid structures, unsupported constructs, conflicts, and degradations have stable codes and source/location context.
- References: local, relative-file, and remote references cover component groups with caching, cycle detection, multi-source conflict handling, and dependency tracking.
- Mappings: enum configuration and vendor extensions have deterministic precedence and unknown fallback; model, property, parameter, operation, schema, type, and import mappings are validated.
- HTTP: path/query/header/cookie serialization and supported style/explode/allowReserved combinations are correct; JSON, multipart, form-urlencoded, text, and binary transfers work.
- Responses: multiple 2xx, 204,
2XX,default, error models, headers, rawHttpResponse, and byte/stream output are represented. - 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.
- Client metadata: servers/base URLs and security requirements are available while remaining compatible with host Dio interceptors.
- Lifecycle: configuration is effective; manifest locking/hashing, unchanged skips, safe stale cleanup, filters, and build_runner integration are complete.
- 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.
- 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
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.