Files

T

mr.koi ea93f09154 Establish the Koi Swagger parser release

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.

2026-06-02 22:00:13 +08:00

4.0 KiB

Raw Blame History

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：

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 等旧字段会继续生效。

命令行

dart run koi_swagger_parser generate --all

常用参数：

--config：指定配置文件路径。
--cwd：指定工作目录。
--dry-run：只解析与渲染，不落盘。
--verbose：打印更多诊断信息。

输出结构

默认会生成：

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 的一键联动模板。

开发与验证

dart pub get
dart format .
dart test

架构设计说明见 doc/ARCHITECTURE.md。

4.0 KiB Raw Blame History Unescape Escape