Advanced

This page covers advanced configuration and features. If you haven't completed the basics yet, start with the Getting Started guide.

Authentication

The generator reads securitySchemes from your OpenAPI spec and emits static factory methods on the aggregator class — one factory per scheme type found. Pass the factory's return value via the interceptors: constructor parameter.

Bearer Token

Emitted when the spec declares type: http, scheme: bearer. The factory returns a Dio Interceptor that sets Authorization: Bearer <token> on every request.

final client = ExampleApiClient(
  interceptors: [
    ExampleApiClient.bearerAuth('your-bearer-token'),
  ],
);

Generated factory:

static Interceptor bearerAuth(String token) => InterceptorsWrapper(
      onRequest: (RequestOptions options, RequestInterceptorHandler handler) {
        options.headers['Authorization'] = 'Bearer $token';
        handler.next(options);
      },
    );

API Key (Header)

Emitted when the spec declares type: apiKey, in: header. The headerName defaults to the name field from the spec's security scheme definition, or 'X-Api-Key' if absent.

ExampleApiClient(
  interceptors: [
    ExampleApiClient.apiKeyAuth('my-key', headerName: 'X-Api-Key'),
  ],
);

Generated factory:

static Interceptor apiKeyAuth(String apiKey,
        {String headerName = 'X-Api-Key'}) =>
    InterceptorsWrapper(
      onRequest: (RequestOptions options, RequestInterceptorHandler handler) {
        options.headers[headerName] = apiKey;
        handler.next(options);
      },
    );

API Key (Query Parameter)

Emitted when the spec declares type: apiKey, in: query. The paramName defaults to the name field from the spec's security scheme definition, or 'api_key' if absent.

ExampleApiClient(
  interceptors: [
    ExampleApiClient.apiKeyQueryAuth('my-key', paramName: 'api_key'),
  ],
);

HTTP Basic Auth

Emitted when the spec declares type: http, scheme: basic. The factory base64-encodes username:password and sets Authorization: Basic <credentials> on every request. The aggregator file automatically imports dart:convert when this factory is emitted.

ExampleApiClient(
  interceptors: [
    ExampleApiClient.basicAuth('alice', 'secret'),
  ],
);

RemoteSpec with Auth Headers

When your OpenAPI spec is served behind authentication (for example a private API gateway), use RemoteSpec with headers. The headers map is used only during code generation to fetch the spec — it does not appear in generated code. Auth header values are never logged, even with debugLogging: true.

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

• The headers map values must be compile-time string literals (the annotation is const).
• A 30-second fetch timeout is enforced with no user-facing override in v0.1.0.

Cache Behavior

When skipIfSpecIsUnchanged: true (the default), the generator computes an MD5 cache key and skips code generation entirely on a cache hit.

The cache key is an MD5 hash of:

1. The raw spec bytes (YAML or JSON, before parsing)
2. The generator version string (kGeneratorVersion)
3. A canonical JSON representation of the codegen-affecting annotation fields: outputDir, clientName, dateTimeConverter, and cleanOutput

Fields that do not affect generated output (debugLogging, skipIfSpecIsUnchanged, cachePath) are excluded from the key.

Cache location: <cachePath>/<key>/cache.json — one directory per unique key. Default cachePath: .dart_tool/dart_openapi_generator_cache.

When is the cache invalidated?

• The spec file changes (byte-level, not just mtime)
• Any of the four codegen-affecting annotation fields change
• The generator version bumps

Set skipIfSpecIsUnchanged: false to always run generation regardless of cache.

dateTimeConverter

Controls how string + format: date-time fields are serialized globally. The setting applies to every DateTime field in every generated model.

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

Changing dateTimeConverter invalidates the MD5 cache and triggers a full regeneration. Per-field overrides are not supported in v0.1.0.

cleanOutput Safety Rules

With cleanOutput: true (the default), the generator deletes files it created in a previous run before writing new output. Deletion is driven by <cachePath>/manifest.json — only files recorded in the manifest are deleted.

The generator refuses to write or clean if outputDir resolves to any of the following:

• The filesystem root (/)
• The project root (.)
• lib — the entire source directory
• Any path containing .. as a path component
• A symlink target

If any condition is met, the build aborts with an error before writing any output.

@OpenApiGenerator(
  inputSpec: LocalSpec('openapi/api.yaml'),
  outputDir: 'lib/generated', // safe — not lib, not ., not /
  cleanOutput: true,          // default
)
class $MyApp {}

Set cleanOutput: false only during debugging — stale generated files can cause dart analyze errors if they reference schemas that have been removed from the spec.

Error Handling via DioException

Every generated service method throws DioException on non-2xx HTTP responses. Catch it to handle API errors:

try {
  final user = await client.users.getUser('user-id');
  print(user.name);
} on DioException catch (e) {
  final statusCode = e.response?.statusCode;
  final body = e.response?.data;
  print('API error $statusCode: $body');
}

• DioException is also thrown for network errors (timeout, no connectivity). Check e.type to distinguish network errors from HTTP errors.
• When a spec operation has non-2xx response codes, the generator emits a comment in the method body:

  // NOTE: only 2xx responses are handled. Add error handling for: 404, 422
  // Access error body via: (e as DioException).response?.data
  

Supported OpenAPI Features

Schemas

Operations

Security Schemes

Name Collision Handling

The generator maintains a NameRegistry built in two passes from the parsed SpecDocument.

Class names (pass 1: collect, pass 2: convert + validate):

• Component schema names → toPascalCase + Dart keyword escape
• Inline request body schemas → <OperationId>Request (or <Method><PathSegments>Request)
• Inline response schemas → <OperationId>Response (or <Method><PathSegments>Response)

If two different spec locations produce the same Dart class name after conversion, generation aborts with an OpenApiParseException that names both conflicting locations. The fix is to rename one schema or operation in the spec.

Field names:

• Property names → toLowerCamelCase + Dart keyword escape
• Dart reserved words (class, default, in, etc.) get a _ suffix — e.g. a spec property named class becomes the Dart field class_. The fromJson/toJson key remains 'class'.

File names:

• Model files: models/<snake_case_class_name>.dart
• Service files: services/<tag_snake_case>_api.dart
• Tag-to-filename conversion lowercases and replaces spaces/hyphens with underscores (does not apply PascalCase splitting — PetStore tag → petstore_api.dart, not pet_store_api.dart).

Known Limitations

• No anyOf support. Schemas using anyOf cause a parse error. Use oneOf with a discriminator as an alternative.
• Same-document $ref only. External file or URL references are not resolved — they cause a parse error. All referenced schemas must be in components/schemas of the same spec file.
• No oneOf without discriminator. The sealed class is generated but fromJson throws UnimplementedError at runtime. The spec must include a discriminator.propertyName.
• in: cookie parameters are not generated. The generator logs a warning and recommends Dio interceptors for cookie-based auth.
• requestBody on GET/HEAD/OPTIONS is not sent. A warning is logged; HTTP semantics prevent sending a body on these methods.
• Per-field dateTimeConverter overrides are not supported. The setting applies globally.
• No webhooks or root-level pathItems (OpenAPI 3.1/3.2). Only paths and components/schemas are processed.
• Only application/json request/response bodies. Multipart, form-encoded, and other content types are not generated.

See also: Getting Started · Annotation Reference · Generated Code