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.
351 lines
9.8 KiB
Markdown
351 lines
9.8 KiB
Markdown
# 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)
|