mr.koi
ea93f09154
Prepare the OpenAPI parser and Dart generator as a publishable Koi package with CLI entrypoint, docs, examples, tests, and pub.dev release metadata. Constraint: Initial GitHub import follows koi_blueprint_flutter identity mr.koi <i@mrkoi.is>. Rejected: Keep local runtime state in the initial repository | .dart_tool, .omx, and pubspec.lock are ignored for a reusable package source tree. Confidence: high Scope-risk: moderate Directive: Keep generated-output behavior covered by parser and generator tests before changing rendering rules. Tested: dart analyze; dart test; PUB_HOSTED_URL=https://pub.dev dart pub publish --dry-run Not-tested: End-to-end downstream build_runner compilation of generated Retrofit/Freezed output.
138 lines
4.0 KiB
Markdown
138 lines
4.0 KiB
Markdown
# koi_swagger_parser
|
||
|
||
`koi_swagger_parser` 是一个面向 Koi 生态的新一代 OpenAPI 解析与 Dart 代码生成器，目标不是继续修补旧式 Swagger 生成链，而是为未来的 `koi_blueprint_flutter` 提供一套更稳、更清晰、更可扩展的基础设施。
|
||
|
||
当前版本聚焦 Koi/FastAPI 场景，优先解决这几类问题：
|
||
|
||
- OpenAPI 3.1 下 `anyOf[T, null]`、`type: [T, null]` 的 nullable 解析。
|
||
- FastAPI `code/message/data` 成功 envelope 的识别与外部泛型包装。
|
||
- `multipart/form-data` 请求体生成 `@MultiPart()` + `@Part()`，并按 preset 选择二进制类型。
|
||
- `oneOf` / `anyOf` + discriminator 生成 sealed union wrapper。
|
||
- 以 Koi 目录结构输出 `api/`、`api_models/request|result|shared|enums/`。
|
||
- 兼容旧版 `generator_config.yaml`，平滑替换 `swagger_generator_flutter`。
|
||
|
||
## 设计目标
|
||
|
||
- 解析层和 Koi 业务约束解耦：parser core 不硬编码 `BaseResult`。
|
||
- 先产出中间表示（IR），再做 Koi 风格渲染，方便未来扩展到 `koi_blueprint_flutter`。
|
||
- 默认以 Retrofit + Freezed 为输出基线，但 response wrapper 可配置。
|
||
- 对 FastAPI/SQLAlchemy 风格服务端有良好适配，同时不把服务端补丁写死在生成器里。
|
||
|
||
## 配置文件
|
||
|
||
推荐使用 `koi_swagger_parser.yaml`：
|
||
|
||
```yaml
|
||
input:
|
||
swagger_urls:
|
||
- url: ./openapi.json
|
||
enabled: true
|
||
|
||
output:
|
||
base_dir: ./lib/src
|
||
api_dir: ./lib/src/api
|
||
models_dir: ./lib/src/api_models
|
||
included_tags:
|
||
- auth
|
||
- stores
|
||
- materials
|
||
split_by_tags: true
|
||
extract_version_from_url: false
|
||
|
||
generation:
|
||
preset:
|
||
name: koi_flutter
|
||
api:
|
||
enabled: true
|
||
use_retrofit: true
|
||
cancel_token_support: true
|
||
client:
|
||
class_name: DbaApiClient
|
||
file_name: dba_api_client
|
||
response_wrapper:
|
||
mode: external_generic
|
||
success_data_field: data
|
||
detect_standard_envelope: true
|
||
external_generic:
|
||
import: package:dba_network/dba_network.dart
|
||
class_name: BaseResult
|
||
models:
|
||
enabled: true
|
||
class_prefix: Koi
|
||
default_non_nullable_list_to_empty: true
|
||
json_serializable:
|
||
checked: true
|
||
explicit_to_json: true
|
||
include_if_null: false
|
||
formatting:
|
||
run_dart_format: true
|
||
```
|
||
|
||
也兼容旧版 `generator_config.yaml`：
|
||
|
||
- `generation.api.base_result_import` 会自动映射为 `response_wrapper.mode = external_generic`。
|
||
- `output.included_tags`、`generation.models.class_prefix` 等旧字段会继续生效。
|
||
|
||
## 命令行
|
||
|
||
```bash
|
||
dart run koi_swagger_parser generate --all
|
||
```
|
||
|
||
常用参数：
|
||
|
||
- `--config`：指定配置文件路径。
|
||
- `--cwd`：指定工作目录。
|
||
- `--dry-run`：只解析与渲染，不落盘。
|
||
- `--verbose`：打印更多诊断信息。
|
||
|
||
## 输出结构
|
||
|
||
默认会生成：
|
||
|
||
```text
|
||
lib/src/
|
||
api/
|
||
dba_api_client.dart
|
||
index.dart
|
||
v1/
|
||
index.dart
|
||
auth_api.dart
|
||
stores_api.dart
|
||
api_models/
|
||
api_models.dart
|
||
request/
|
||
result/
|
||
shared/
|
||
enums/
|
||
```
|
||
|
||
## 当前能力
|
||
|
||
当前版本已经覆盖 Koi 当前最需要的能力：
|
||
|
||
- OpenAPI 3.1 文档加载（本地 JSON/YAML、远程 URL、多 source merge）。
|
||
- `object` / `array` / `enum` / `additionalProperties` / `allOf` 基础支持。
|
||
- nullable query/path/body 字段解析。
|
||
- FastAPI envelope 检测与 `BaseResult<T>` 外部包装。
|
||
- `multipart/form-data` 生成 `MultipartFile` / `File` / `Uint8List` / `String` 等 preset 驱动参数。
|
||
- `oneOf` / `anyOf` + discriminator 生成 sealed union wrapper，并可被其他模型继续引用。
|
||
- Retrofit API 文件、Freezed 模型文件、分组 index 文件生成。
|
||
|
||
下一阶段可以继续往前加：
|
||
|
||
- 更丰富的 multipart metadata（如 encoding / runtime fileName / contentType preset）。
|
||
- 无 discriminator 的更强联合类型兜底策略。
|
||
- 更多 preset（例如 Chopper / blueprint preset / 网络层集成 preset）。
|
||
- 与 `koi_blueprint_flutter` 的一键联动模板。
|
||
|
||
## 开发与验证
|
||
|
||
```bash
|
||
dart pub get
|
||
dart format .
|
||
dart test
|
||
```
|
||
|
||
架构设计说明见 `doc/ARCHITECTURE.md`。
|