Release 0.2.0
Complete OpenAPI 3.0/3.1 generation, diagnostics, lifecycle safety, enum and naming mappings, bilingual documentation, examples, and pub.dev release validation.
This commit is contained in:
mr.koi
@@ -0,0 +1,237 @@
|
||||
# Migrating from swagger_generator_flutter
|
||||
|
||||
[English](MIGRATION.md) | [Chinese (Simplified)](zh-CN/MIGRATION.md)
|
||||
|
||||
This guide covers migration from the `generator_config.yaml` conventions used
|
||||
by `swagger_generator_flutter`. Perform the migration in the consuming
|
||||
Dart/Flutter repository; no local machine path is assumed.
|
||||
|
||||
## Recommended sequence
|
||||
|
||||
1. Preserve the old generated output on a separate branch.
|
||||
2. Copy
|
||||
[koi_swagger_parser.example.yaml](../koi_swagger_parser.example.yaml) and
|
||||
migrate only sources, output roots, and response wrapping first.
|
||||
3. Set `clean_stale_files: false` for the first run and use `--dry-run`.
|
||||
4. Generate into temporary directories and compare API signatures, JSON keys,
|
||||
and imports.
|
||||
5. Migrate enum, naming, and custom type mappings.
|
||||
6. Run build_runner, `dart analyze`, and the host project's tests.
|
||||
7. After reviewing the output, switch to the final directories and enable
|
||||
`clean_stale_files: true`.
|
||||
|
||||
## Settings that carry over
|
||||
|
||||
| Previous field | New field or behavior |
|
||||
|---|---|
|
||||
| `input.swagger_urls` | Same name; strings/objects, `enabled`, local paths, and HTTP(S) sources are supported |
|
||||
| `output.base_dir/api_dir/models_dir` | Same names |
|
||||
| `output.included_tags/excluded_tags` | Same names, with glob and regular-expression support |
|
||||
| `output.split_by_tags` | Same name |
|
||||
| `generation.api.client.class_name/file_name` | Same names |
|
||||
| `generation.api.cancel_token_support` | Same name |
|
||||
| `generation.api.base_result_import` | Compatibility input; selects `external_generic` with `BaseResult` |
|
||||
| `generation.models.class_prefix` | Same name |
|
||||
| `generation.models.json_serializable.*` | Same names |
|
||||
| `generation.models.enum_key_mappings` | Still accepted; migrate toward `enum_mappings` |
|
||||
| `formatting.run_dart_format` | Same name |
|
||||
|
||||
An existing enum mapping does not need to be rewritten immediately:
|
||||
|
||||
```yaml
|
||||
generation:
|
||||
models:
|
||||
enum_key_mappings:
|
||||
TaskType:
|
||||
- value: 1
|
||||
name: spotCheck
|
||||
description: Spot check
|
||||
```
|
||||
|
||||
When both fields map the same wire value, `enum_mappings` wins. The generator
|
||||
also recognizes `x-enumNames`, `x-enum-varnames`, and `x-enum-values`.
|
||||
|
||||
## Settings that need rewriting
|
||||
|
||||
### Response wrapper
|
||||
|
||||
Previous form:
|
||||
|
||||
```yaml
|
||||
generation:
|
||||
api:
|
||||
base_result_type: BaseResult
|
||||
base_result_import: package:app/network/base_result.dart
|
||||
```
|
||||
|
||||
Recommended form:
|
||||
|
||||
```yaml
|
||||
generation:
|
||||
api:
|
||||
response_wrapper:
|
||||
mode: external_generic
|
||||
detect_standard_envelope: true
|
||||
success_data_field: data
|
||||
external_generic:
|
||||
import: package:app/network/base_result.dart
|
||||
class_name: BaseResult
|
||||
```
|
||||
|
||||
There is no automatic one-to-one migration for
|
||||
`base_page_result_type/base_page_result_import`. Prefer an accurate pagination
|
||||
schema in OpenAPI. To reuse an existing type, use
|
||||
`generation.mappings.schemas`, or keep the server envelope in `passthrough`
|
||||
mode.
|
||||
|
||||
### Type and import mappings
|
||||
|
||||
Previous top-level `type_mapping` and `imports` values were global. The new
|
||||
configuration groups validated mappings under `generation.mappings`:
|
||||
|
||||
```yaml
|
||||
generation:
|
||||
mappings:
|
||||
schemas:
|
||||
Money:
|
||||
type: Money
|
||||
import: package:money2/money2.dart
|
||||
types:
|
||||
string:uuid:
|
||||
type: UuidValue
|
||||
import: package:uuid/uuid_value.dart
|
||||
string:date-time: DateTime
|
||||
imports:
|
||||
UuidValue: package:uuid/uuid_value.dart
|
||||
```
|
||||
|
||||
Type lookup tries `type:format` before `type`. A `schemas` entry means that the
|
||||
schema is completely supplied by an external type and no Dart model is
|
||||
generated for it.
|
||||
|
||||
### Ignored directories and files
|
||||
|
||||
The previous `ignored_directories` and `ignored_files` settings skipped files
|
||||
after rendering and could leave APIs referencing missing models. Replace them
|
||||
with semantic source filters:
|
||||
|
||||
```yaml
|
||||
output:
|
||||
excluded_paths:
|
||||
- /api/v1/legacy/**
|
||||
excluded_operations:
|
||||
- regex:^internal
|
||||
excluded_models:
|
||||
- Legacy*
|
||||
```
|
||||
|
||||
If a retained operation depends on an excluded model, generation fails with
|
||||
`filter.required_model_excluded`. There is intentionally no setting that
|
||||
arbitrarily drops a rendered file.
|
||||
|
||||
### Version extraction
|
||||
|
||||
Paths such as `/api/v1/` and `/v2/` are grouped automatically. To also try
|
||||
extracting a version from the source URL:
|
||||
|
||||
```yaml
|
||||
output:
|
||||
extract_version_from_url: true
|
||||
```
|
||||
|
||||
The previous custom
|
||||
`generation.api.version_extraction.pattern/default_version` setting has no
|
||||
one-to-one equivalent. A URL extraction failure produces a diagnostic and
|
||||
falls back to path-based grouping.
|
||||
|
||||
### build_runner
|
||||
|
||||
The previous workflow commonly ran build_runner separately. It can now be
|
||||
part of generation:
|
||||
|
||||
```yaml
|
||||
formatting:
|
||||
run_dart_format: true
|
||||
run_build_runner: true
|
||||
build_runner_mode: build
|
||||
delete_conflicting_outputs: true
|
||||
```
|
||||
|
||||
For interactive development:
|
||||
|
||||
```bash
|
||||
dart run koi_swagger_parser generate --watch
|
||||
```
|
||||
|
||||
Watch mode is long-running and should not be used for a one-shot CI job.
|
||||
|
||||
## Previous settings that are not read
|
||||
|
||||
These fields produce a `config.unknown_key` warning:
|
||||
|
||||
- `generator.name/version/author/copyright`;
|
||||
- `input.validate_schema/strict_mode`;
|
||||
- `output.api_file_suffix/model_file_suffix`;
|
||||
- `generation.api.use_dio/parser/method_naming`;
|
||||
- `generation.models.class_naming/field_naming/use_const_constructor`;
|
||||
- top-level `validation.on_error/on_warning`;
|
||||
- top-level generic import ordering/grouping settings.
|
||||
|
||||
The new generator uses structured errors for cases that would break wire
|
||||
semantics or compilation. It does not provide a warn/ignore override for those
|
||||
errors. Unsupported constructs that can be omitted safely, such as callbacks
|
||||
and links, produce warnings.
|
||||
|
||||
## Generated-code differences to review
|
||||
|
||||
- A schema with read-only/write-only fields can become `FooRequest` and
|
||||
`FooResponse`.
|
||||
- An optional field whose schema disallows null still uses a nullable Dart
|
||||
argument to represent absence, together with `disallowNullValue`; explicit
|
||||
JSON null is rejected.
|
||||
- A root object with `properties` plus `additionalProperties` flattens extras
|
||||
into the JSON root.
|
||||
- A `default` response is never treated as successful.
|
||||
- Complex parameter styles can introduce a public transport adapter and a
|
||||
private Retrofit delegate.
|
||||
- API methods can return `HttpResponse<T>`; binary output can use bytes or a
|
||||
stream.
|
||||
- Generated enums include wire conversion, and unknown fallback uses an
|
||||
internal sentinel wire value.
|
||||
- Stale files are removed only through manifest ownership; a user-modified
|
||||
stale file is preserved.
|
||||
|
||||
## CLI comparison
|
||||
|
||||
Previous:
|
||||
|
||||
```bash
|
||||
dart run swagger_generator_flutter generate --all
|
||||
```
|
||||
|
||||
New:
|
||||
|
||||
```bash
|
||||
dart run koi_swagger_parser generate --all
|
||||
dart run koi_swagger_parser generate --dry-run --verbose
|
||||
```
|
||||
|
||||
Previous `--api`, `--models`, `--docs`, and CLI tag overrides are not retained.
|
||||
Use `generation.*.enabled` and output filters. The current generator does not
|
||||
emit a separate API documentation site.
|
||||
|
||||
## Acceptance checklist
|
||||
|
||||
- The dry run has no error diagnostics.
|
||||
- Enum wire values and Dart member names match the previous contract.
|
||||
- Request/response directional models contain the expected fields.
|
||||
- Cookie, query, and path serialization produces equivalent requests.
|
||||
- Error and default responses are not decoded as successful responses.
|
||||
- External custom types have correct imports and JSON conversion.
|
||||
- `dart run build_runner build --delete-conflicting-outputs` succeeds.
|
||||
- `dart analyze` and host-project tests pass.
|
||||
- The second generation reports `lifecycle.unchanged_skipped`.
|
||||
- Removing an operation deletes only unmodified files owned by the manifest.
|
||||
|
||||
For every available backend fixture, compare runtime serialization in addition
|
||||
to generated source text.
|
||||
Reference in New Issue
Block a user