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.
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# 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.
|