# koi_swagger_parser

[English](README.md) | [简体中文](README.zh-CN.md)

`koi_swagger_parser` 是面向 Dio、Retrofit、Freezed 和
json_serializable 项目的 OpenAPI 3.0/3.1 Dart/Flutter 客户端生成器。它将文档
加载、`$ref` 解析、校验、中间表示（IR）、渲染和安全的增量写入相互分离。

生成代码采用面向 Koi 项目的目录结构：

```text
lib/src/
  api/
    api_client.dart
    index.dart
    v1/
      index.dart
      stores_api.dart
  api_models/
    api_models.dart
    request/
    result/
    shared/
    enums/
```

## 功能

- 本地 JSON/YAML、HTTP(S)、多个根文档，以及本地、相对、file 和远程 `$ref`；
- component 引用解析、缓存、循环检测、确定性冲突处理和依赖追踪；
- Retrofit API，以及 Freezed/json_serializable 请求、响应、共享、枚举和联合模型；
- `enum_mappings`、兼容字段 `enum_key_mappings`、`x-enumNames`、
  `x-enum-varnames`、`x-enum-values`、描述和可选 unknown enum fallback；
- model、property、parameter、operation、schema、type 和 import 映射及冲突诊断；
- OpenAPI path、query、header 和 cookie 参数，包括已支持的 style、explode 和
  `allowReserved` 组合；
- JSON、text、multipart、form-urlencoded 和 binary 请求，以及 bytes/stream 下载；
- 多个成功响应、204、`2XX`、`default`、错误响应、响应头和可选
  `HttpResponse<T>` 返回值；
- required、nullable、absent 语义，readOnly/writeOnly 投影，
  `additionalProperties`、`allOf` 和已支持的 `oneOf`/`anyOf`；
- server variables 和 security metadata；凭证仍由宿主应用的 Dio interceptor
  或 provider 注入；
- 精确、glob 和正则过滤；
- 带文件锁的 manifest、SHA-256 变更检测、安全 stale cleanup、原子写入、
  dry-run 和可选 build_runner 集成。

准确边界见[兼容性矩阵](doc/zh-CN/COMPATIBILITY.md)。

## 环境要求

- Dart SDK `^3.11.0`；
- JSON 或 YAML 格式的 OpenAPI 3.0.x/3.1.x 文档；
- 同时生成 API 和模型时，宿主 Dart/Flutter 项目需配置 Retrofit、Freezed 和
  json_serializable。

## 安装

在宿主项目中把生成器添加为开发依赖：

```bash
dart pub add --dev koi_swagger_parser
```

典型生成客户端需要以下宿主运行时依赖：

```bash
dart pub add dio retrofit freezed_annotation json_annotation
```

添加相应代码生成工具：

```bash
dart pub add --dev build_runner retrofit_generator freezed json_serializable
```

Flutter 项目若统一使用 Flutter 管理依赖，可把 `dart pub add` 换成
`flutter pub add`。

## 快速开始

1. 将[完整配置模板](koi_swagger_parser.example.yaml)复制为宿主项目中的
   `koi_swagger_parser.yaml`。
2. 至少设置一个 OpenAPI source 和输出目录：

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

generation:
  preset:
    name: koi_flutter
  api:
    enabled: true
    use_retrofit: true
    response_wrapper:
      mode: passthrough
  models:
    enabled: true
    class_prefix: Koi

formatting:
  run_dart_format: true
  run_build_runner: true
  build_runner_mode: build
```

3. 预览变更：

```bash
dart run koi_swagger_parser generate --all --dry-run
```

4. 生成客户端：

```bash
dart run koi_swagger_parser generate --all
```

当 `formatting.run_build_runner` 为 `false` 时，单独执行：

```bash
dart run build_runner build --delete-conflicting-outputs
```

## CLI 用法

```text
dart run koi_swagger_parser generate [options]

--all, -a       生成所有已启用资源；为了命令兼容而保留。
--config, -c    配置文件路径。
--cwd           宿主项目工作目录。
--dry-run       完成解析和渲染，但不写入或删除文件。
--watch         生成后启动 build_runner watch。
--verbose, -v   显示 info 诊断和失败堆栈。
```

加载器按以下顺序在工作目录中查找：

1. `koi_swagger_parser.yaml`
2. `koi_swagger_parser.yml`
3. `generator_config.yaml`
4. `generator_config.yml`

当 `--config` 指向当前目录外的文件且未设置 `--cwd` 时，配置文件目录会成为宿主
项目工作目录。相对 source 和输出路径始终以配置文件目录解析；`--cwd` 只改变
宿主项目命令的运行位置，不改变这些路径语义。

## Library 用法

也可以通过 Dart API 使用相同流水线：

```dart
import 'package:koi_swagger_parser/koi_swagger_parser.dart';

Future<void> main() async {
  final result = await const KoiSwaggerParser().generate(
    configPath: 'koi_swagger_parser.yaml',
    dryRun: true,
  );

  print('${result.operationsCount} operations');
  print('${result.modelsCount} models');
  for (final diagnostic in result.diagnostics) {
    print(diagnostic.format());
  }
}
```

遇到 error 诊断时会抛出 `KoiDiagnosticException`。自动化应匹配诊断 `code`，
而不是 message 文本。详见[诊断参考](doc/zh-CN/DIAGNOSTICS.md)。

## Enum 映射

可在配置中把枚举 wire value 映射成稳定的 Dart 成员名：

```yaml
generation:
  models:
    enum_unknown_fallback: true
    enum_mappings:
      OrderStatus:
        - value: pending
          name: waitingForPayment
          description: 等待付款
        - value: done
          name: completed
          description: 已完成
```

也支持 map 写法：

```yaml
generation:
  models:
    enum_mappings:
      OrderStatus:
        pending: waitingForPayment
        done:
          name: completed
          description: 已完成
```

兼容字段 `enum_key_mappings` 仍然可用。名称解析优先级为：

1. `enum_mappings`
2. `enum_key_mappings`
3. `x-enumNames`、`x-enum-names` 或 `x-enum-varnames`
4. `x-enum-values`
5. 根据 wire value 自动生成的名称

描述优先采用配置，其次是 `x-enumDescriptions`、
`x-enum-descriptions` 和 `x-enum-values.description`。启用
`enum_unknown_fallback: true` 后，生成器会添加稳定的 `unknown` 成员，并在
枚举引用上应用 `JsonKey.unknownEnumValue`。

## 命名与类型映射

```yaml
generation:
  mappings:
    models:
      UserDto: User
    properties:
      UserDto:
        user_id: id
    parameters:
      getUser:
        user_id: id
    operations:
      getUser: fetchUser
      "DELETE /api/v1/users/{id}": removeUser
    schemas:
      Money:
        type: Money
        import: package:money2/money2.dart
    types:
      string:uuid:
        type: UuidValue
        import: package:uuid/uuid_value.dart
      integer:int64: int
    imports:
      UuidValue: package:uuid/uuid_value.dart
```

operation 映射键可以是 `operationId` 或 `METHOD /path`。schema 映射表示该
schema 由外部实现，因此不会为其生成模型。外部类型必须提供生成用法所需的
JSON 转换能力。

## 响应与传输

```yaml
generation:
  api:
    cancel_token_support: true
    response_mode: http_response       # body | http_response
    binary_response_mode: bytes        # bytes | stream
    client:
      class_name: ApiClient
      file_name: api_client
    response_wrapper:
      mode: external_generic           # passthrough | external_generic
      success_data_field: data
      detect_standard_envelope: true
      external_generic:
        import: package:your_network/your_network.dart
        class_name: BaseResult
```

当 Retrofit annotation 无法表达已支持的 matrix、label、cookie、deepObject
或 reserved-character 参数时，生成器会在私有 Retrofit delegate 前生成 typed
transport adapter。`default` response 始终被视为错误响应。

## 过滤与生命周期

```yaml
output:
  included_tags: [stores]
  excluded_paths: [/internal/**]
  included_operations: [getStore, "POST /api/v1/stores"]
  excluded_models: [Legacy*]
  clean_stale_files: true
  skip_if_unchanged: true
  manifest_path: ./.dart_tool/koi_swagger_parser/manifest.json
```

过滤器支持精确值、`*`、`?`、`**` glob，或带 `regex:` 前缀的 Dart 正则。
exclude 优先于 include。`included_models` 可把原本未被引用的 component 加为
生成根。

manifest 只记录本生成器拥有的文件。仅当旧生成文件仍位于配置的 API/model
输出根内，且内容仍与旧 manifest hash 相同时，stale cleanup 才会删除它。
被修改的文件及旁边的手写文件会保留。

## 限制

当前版本明确不生成：

- Swagger/OpenAPI 2.0 客户端；
- callbacks、webhooks 或 Link Object 调用链；
- XML、Protobuf 或任意自定义 codec；
- 完整 JSON Schema 2020-12；
- server stub、mock server 或非 Dart 目标；
- 可由外部接入的 renderer/template API。

不支持或存在信息损失的结构会产生结构化 warning/error，不会静默宣称完全
支持。为新的 schema corpus 引入本生成器前请查看[兼容性](doc/zh-CN/COMPATIBILITY.md)。

## 文档

- [配置参考](doc/zh-CN/CONFIGURATION.md)
- [兼容性矩阵](doc/zh-CN/COMPATIBILITY.md)
- [诊断参考](doc/zh-CN/DIAGNOSTICS.md)
- [架构](doc/zh-CN/ARCHITECTURE.md)
- [从 swagger_generator_flutter 迁移](doc/zh-CN/MIGRATION.md)
- [更新日志](doc/zh-CN/CHANGELOG.md)

## 开发

```bash
dart pub get
dart format .
dart analyze
dart test
dart run tool/verify_generated_package.dart
```

最后一条命令会创建临时 Dart 包，调用本生成器及其 build_runner 集成，并在
生成的包内执行分析和运行时测试。

## 支持与贡献

请通过 [GitHub Issues](https://github.com/mrkoi-is/koi_swagger_parser/issues)
提交可复现的问题和功能需求。请附带生成器版本、Dart 版本、最小 OpenAPI 文档、
相关配置和诊断 code；分享前移除凭证和私有服务数据。

贡献代码时应增加聚焦的测试；行为变化时同步兼容性矩阵和配置参考。提交 PR 前
请运行上述开发检查。

## 许可证

[MIT](LICENSE)