flap #

Fast, zero-dependency OpenAPI → Dart/Flutter client generator.

flap lowers OpenAPI 3.0, 3.1, and Swagger 2.0 specs into idiomatic, production-ready Dart/Flutter clients using package:freezed and json_serializable — no Java, no Node.js, no Docker required.

Table of contents #

• Features
• Installation
  • Supported platforms
  • Build from source
• Quick start
• Output layout
• Generated client
  • Dio (default)
  • http
• PATCH / tri-state fields
• Schema mapping
  • Type mapping
  • Template overrides
• Programmatic use
• Project structure
  • Crate responsibilities
• CLI reference
• Dependencies
• CI / release workflow
• License
• Author

Features #

• Spec support — OpenAPI 3.0, OpenAPI 3.1, and Swagger 2.0 (YAML or JSON, local file or remote URL)
• Two HTTP backends — package:dio (default, full-featured) or package:http (lightweight)
• Sound null safety — Dart 3 / freezed 3 output; legacy null-unsafe output is available opt-in via --null-unsafe
• Full schema coverage — objects, arrays, maps, enums, discriminated unions (oneOf + discriminator), untagged unions (anyOf/oneOf), allOf inheritance, recursive types
• PATCH tri-state semantics — Optional<T?> wrapper for nullable: true + optional fields, distinguishing "key absent" from "key explicitly null"
• Security schemes — apiKey (header, query, cookie), HTTP Bearer, HTTP Basic, OAuth 2.0, OpenID Connect; credentials injected via a Dio interceptor or per-request http headers/query/cookies automatically
• Response headers — typed Dart 3 named-record return types for operations with declared response headers
• default: values — emitted as Freezed @Default(...) annotations
• date-time format → DateTime; float/double format → double; binary format → List<int>
• Parameter serialization — OpenAPI style/explode (form, deepObject, spaceDelimited, pipeDelimited) and Swagger collectionFormat for query parameters; form-encoded bodies use bracket keys for nested objects
• Battle-tested — the full Stripe OpenAPI document (594 operations, 1,454 schemas) generates, builds with build_runner, and analyzes cleanly with both backends
• Lenient loading — inline objects become named classes, root-level enums/primitives are supported, $ref parameters/responses/request bodies and path-level parameters resolve, and unsupported constructs degrade to dynamic with a warning instead of aborting
• Multipart uploads — multipart/form-data request bodies via FormData / MultipartRequest
• Multiple servers — servers: array emitted as a typed abstract final class FooClientUrls
• Incremental builds — lockfile per spec × backend keyed on the spec's SHA-256; unchanged specs are skipped
• Template overrides — swap any generated file with a Jinja2 template or a verbatim file
• Type/import mapping — replace generated schema types with your own hand-written classes

Installation #

dart pub global activate flap

On first run, flap downloads the pre-built Rust binary for your platform and caches it at ~/.flap/bin/<version>/. Subsequent runs are instant.

Supported platforms #

Build from source #

Requires the Rust toolchain (stable).

git clone https://github.com/miracle101000/flap-dart
cd flap-dart
cargo build --release --bin generate_dart

Point the Dart wrapper at the result with the FLAP_BINARY environment variable:

FLAP_BINARY=$PWD/target/release/generate_dart flap --out ./generated path/to/spec.yaml

Quick start #

# Generate a Dio client (default)
flap --out ./generated path/to/openapi.yaml

# Generate an http-package client
flap --out ./generated --client=http path/to/openapi.yaml

# Generate from a remote URL
flap --out ./generated https://petstore3.swagger.io/api/v3/openapi.yaml

# Multiple specs in one pass
flap --out ./generated specs/users.yaml specs/payments.yaml

# Force regeneration even if the spec has not changed
flap --out ./generated --force path/to/openapi.yaml

Each spec gets its own subdirectory under --out, named after the spec file stem (e.g. openapi.yaml → generated/openapi/). Inside it you will find one Dart file per schema (plus one per inline enum), one client file, flap_utils.dart (the Optional<T?> runtime), and a .flap.lock.* incremental build marker. Pass --null-unsafe to additionally emit legacy null-unsafe code into a null_unsafe/ subfolder — note that Dart 3 SDKs cannot compile that dialect.

Output layout #

generated/
└── petstore/
    ├── pet.dart              # @freezed model
    ├── pets.dart             # typedef List<Pet>
    ├── error_model.dart      # @freezed model (`Error` is renamed to avoid dart:core)
    ├── swagger_petstore_client.dart   # API client
    ├── flap_utils.dart       # Optional<T?> runtime + converters
    └── .flap.lock.null_safe.dio

Generated client #

Dio (default) #

final client = SwaggerPetstoreClient(
  baseUrl: SwaggerPetstoreClientUrls.server0, // when multiple servers declared
  bearerAuth: myJwtToken,                     // or apiKey: ..., appId: ...
);

// Typed return — body deserialized automatically
final pet = await client.showPetById(petId: '42');

// Response headers included in a named record when declared in the spec
final (:body, :xNext) = await client.listPets(limit: 10);

// Enum parameters send their wire value; DateTime parameters are ISO 8601;
// path parameters are URI-encoded.

http #

final client = SwaggerPetstoreClient(
  bearerAuth: myJwtToken,
  client: myCustomHttpClient, // optional; defaults to http.Client()
);

try {
  final pet = await client.showPetById(petId: '42');
} on SwaggerPetstoreClientException catch (e) {
  print('${e.statusCode}: ${e.body}'); // thrown for every non-2xx response
}

PATCH / tri-state fields #

For nullable: true + optional fields (the "PATCH cell" — absent vs. explicitly null), flap emits Optional<T?>:

await client.updateUser(
  id: '42',
  body: UpdateUserRequest(
    id: 'required-field',
    bio: null,                         // required + nullable → String?
    nickname: Optional.present(null),  // optional + nullable → set to null
    displayName: Optional.absent(),    // optional + nullable → omit key entirely
  ),
);

Classes with such fields opt out of the freezed-generated toJson and emit one that omits Optional.absent() keys. flap_utils.dart provides Optional, Optional.of(value) (absent when value is null) and the per-type JsonConverters (OptionalStringConverter, OptionalIntConverter, …) the models use. Wire-side null on input deserialises as Optional.absent().

Enums are emitted as enhanced enums with a value field and an unknown fallback, so a server that adds a new value never breaks deserialisation:

final kind = ShapeKind.fromJson('circle'); // ShapeKind.circle
final later = ShapeKind.fromJson('hexagon'); // ShapeKind.unknown
print(kind.value);                         // 'circle'

Schema mapping #

Type mapping #

Replace a generated schema with your own class:

flap --out ./generated \
  --type-map=Pet=MyAppPet \
  --import-map=MyAppPet=package:myapp/models/pet.dart \
  path/to/petstore.yaml

The generated client will import and use MyAppPet wherever Pet would have appeared. The Pet model file is not emitted.

Template overrides #

Customise any generated file via Jinja2 or verbatim replacement:

flap --out ./generated --template-dir=./templates path/to/openapi.yaml

Resolution order per output file:

1. {template-dir}/{exact-filename} — verbatim copy, highest priority
2. {template-dir}/model.dart.jinja — Jinja2 template applied to every model
3. {template-dir}/client.dart.jinja — Jinja2 template applied to the client
4. {template-dir}/flap_utils.dart — verbatim override for the runtime file
5. Built-in emitter — fallback

The Jinja2 context exposes class_name, schema_name, fields (with dart_name, dart_type, required, nullable, uses_optional_wrapper, json_name, default_expr), imports, extends, null_safety, and more.

Programmatic use #

import 'package:flap/flap.dart';

Future<void> main() async {
  final exitCode = await FlapRunner().run([
    '--out', './generated',
    '--client=http',
    'api/openapi.yaml',
  ]);
  if (exitCode != 0) throw Exception('flap failed with exit code $exitCode');
}

Project structure #

flap/                          # Dart package (pub.flutter-io.cn distribution)
├── bin/flap.dart              # CLI entry point
├── lib/
│   ├── flap.dart              # Public API export
│   └── src/
│       ├── runner.dart        # FlapRunner — locates and invokes the binary
│       ├── binary_manager.dart # Downloads and caches the platform binary
│       ├── platform_info.dart  # Platform slug / archive extension helpers
│       └── version.dart       # Package version (must match pubspec.yaml)
├── test/                      # Dart wrapper tests
│
crates/                        # Rust workspace
├── flap-ir/                   # Intermediate representation (language-agnostic)
│   └── src/lib.rs             # Api, Schema, Operation, TypeRef, SecurityScheme …
├── flap-spec/                 # OpenAPI / Swagger loader and lowering pass
│   └── src/
│       ├── lib.rs             # OpenAPI 3.x parser, validation and lowering → IR
│       └── swagger.rs         # Swagger 2.0 raw types, translated into the 3.x shape
└── flap-emit-dart/            # Dart code emitter
    └── src/lib.rs             # emit_models(), emit_client(), Jinja2 support
│
src/
└── bin/generate_dart.rs       # Rust CLI binary (the thing Dart shells out to)
│
tests/generate.rs              # Fixture-driven integration tests for lowering, emission and the CLI
fixtures/                      # OpenAPI / Swagger spec fixtures used in tests

Crate responsibilities #

CLI reference #

flap --out <dir> [options] <spec> [<spec> ...]

Arguments:
  <spec>                  Path to a local .yaml/.yml/.json file, or an http(s):// URL.
                          OpenAPI 3.x and Swagger 2.0 are detected automatically.
                          Multiple specs may be provided; each is written to its own subdirectory.

Options:
  --out, -o <dir>         Output directory (required).
  --client=<backend>      HTTP client backend: dio (default) or http.
  --force, -f             Regenerate even if the spec has not changed.
  --null-unsafe           Additionally emit legacy null-unsafe code to <dir>/<spec>/null_unsafe/.
  --type-map=A=B          Replace schema A with Dart type B in all generated files.
                          May be repeated.
  --import-map=B=pkg:...  Import URI for a type introduced by --type-map.
                          May be repeated.
  --template-dir, -t <d>  Directory of Jinja2 / verbatim template overrides.
  --help, -h              Print usage.
  --version, -V           Print the version.

Non-fatal spec problems (unsupported constructs degraded to dynamic, skipped headers, …) are printed as warnings; dangling $refs and duplicate operationIds fail the run.

Set FLAP_BINARY=/path/to/generate_dart to make the Dart wrapper use a locally built generator instead of downloading a release binary.

Dependencies #

The generated Dart code requires these packages in the consuming project:

# pubspec.yaml
environment:
  sdk: ^3.8.0              # json_serializable ≥ 6.9 emits null-aware elements

dependencies:
  dio: ^5.0.0              # if using --client=dio (default)
  http: ^1.0.0             # if using --client=http
  freezed_annotation: ^3.0.0
  json_annotation: ^4.12.0

dev_dependencies:
  build_runner: ^2.4.0
  freezed: ^3.0.0
  json_serializable: ^6.9.0

After generation, run the build runner once:

dart run build_runner build --delete-conflicting-outputs

CI / release workflow #

The GitHub Actions workflow (.github/workflows/ci.yml) runs on every push and pull request:

• Rust — cargo fmt, cargo clippy, cargo test (unit + fixture-driven integration tests) on Ubuntu, macOS, and Windows
• Dart — dart analyze, dart test, dart pub publish --dry-run

The release workflow (.github/workflows/release.yml) triggers on v* tags:

1. Checks the tag matches pubspec.yaml, then builds the Rust binary for all five targets in parallel
2. Packages each into a .tar.gz (Unix) or .zip (Windows) with a SHA-256 sidecar
3. Creates a GitHub Release and attaches all archives
4. Publishes the Dart package to pub.flutter-io.cn via OIDC

License #

MIT — see LICENSE.

Author #

Miracle Okolo — LinkedIn · GitHub