Annotation Reference

The @OpenApiGenerator annotation is the single configuration point for code generation. Place it on any Dart class to trigger generation via build_runner.

lib/main.dart

import 'package:dart_openapi_generator_annotations/dart_openapi_generator_annotations.dart';

@OpenApiGenerator(
  inputSpec: LocalSpec('openapi/api.yaml'),
  outputDir: 'lib/generated',
)
class $MyApp {}

@OpenApiGenerator

inputSpecInputSpecrequired

The source of the OpenAPI spec. Use LocalSpec for a local file or RemoteSpec for an HTTPS URL. See InputSpec below.

outputDirStringrequired

Directory where generated Dart files are written, relative to the package root (where pubspec.yaml lives). Example: 'lib/generated'.

clientNameString

Name of the generated aggregator client class. Defaults to 'ApiClient'. Example: 'PetstoreClient'.

skipIfSpecIsUnchangedbool

When true (the default), the generator computes an MD5 cache key from spec bytes, generator version, and codegen-affecting annotation fields. On a cache hit the build step is a no-op. Set to false to always regenerate regardless of cache.

cachePathString

Directory where the spec cache is stored, relative to the package root. Defaults to '.dart_tool/dart_openapi_generator_cache'. Changing this value invalidates any existing cache.

cleanOutputbool

When true (the default), files listed in the prior-run manifest are deleted before generation begins. Files not in the manifest are never touched. Set to false to keep stale generated files (useful during debugging, but stale files can cause dart analyze errors). See Advanced — cleanOutput for safety rules.

dateTimeConverterDateTimeConverter

Strategy for serializing string + format: date-time schema fields. Defaults to DateTimeConverter.iso8601. See DateTimeConverter below.

debugLoggingbool

When true, the generator logs every file written, every file deleted, cache-hit/miss decisions, and parse warnings. Defaults to false (errors only).

InputSpec

InputSpec is a sealed class. You must use either LocalSpec or RemoteSpec — it cannot be constructed directly.

LocalSpec

Use for a spec file on disk. The path is relative to the package root (where pubspec.yaml lives). Absolute paths are also accepted.

Field	Type	Description
`path`	`String`	Path to the spec file. Relative to the package root.

@OpenApiGenerator(
  inputSpec: LocalSpec('openapi/api.yaml'),
  outputDir: 'lib/generated',
)
class $MyApp {}

RemoteSpec

Use for a spec served over HTTPS. Only https:// URLs are accepted — http:// URLs are rejected before any network request is made. A 30-second fetch timeout is enforced.

Field	Type	Description
`url`	`String`	HTTPS URL of the OpenAPI spec. Required.
`headers`	`Map<String, String>?`	Optional HTTP headers sent with the fetch request. Defaults to `null` (no extra headers). Header values are never logged, even with `debugLogging: true`.

@OpenApiGenerator(
  inputSpec: RemoteSpec(
    'https://example.com/openapi.json',
    headers: {'Authorization': 'Bearer my-token'},
  ),
  outputDir: 'lib/generated',
)
class $MyApp {}

The url must use the https:// scheme. HTTP URLs are rejected at generation time with a clear error. The generator also checks that any redirect target is still HTTPS before reading the response body.

DateTimeConverter

Controls how string fields with format: date-time are serialized and deserialized in generated models. Applied globally — per-field overrides are not supported in v0.1.0.

Value	`fromJson`	`toJson`	When to use
`DateTimeConverter.iso8601` (default)	`DateTime.parse(json['field'] as String)`	`instance.field.toIso8601String()`	REST APIs that exchange ISO 8601 strings
`DateTimeConverter.timestamp`	`DateTime.fromMillisecondsSinceEpoch(json['field'] as int)`	`instance.field.millisecondsSinceEpoch`	APIs that use Unix epoch milliseconds

@OpenApiGenerator(
  inputSpec: LocalSpec('openapi/api.yaml'),
  outputDir: 'lib/generated',
  dateTimeConverter: DateTimeConverter.timestamp,
)
class $MyApp {}