# 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`。