Getting Started

This guide walks through setting up dart_openapi_generator in an existing Flutter or Dart project. By the end you will have a generated, type-safe API client ready to use. The guide uses a local OpenAPI spec file — for remote specs see Advanced.

• Add dependencies to pubspec.yaml

  Add these packages, then run dart pub get.

  pubspec.yaml

  dependencies:
    dart_openapi_generator_annotations: ^0.1.0
    dio: ^5.0.0
  
  dev_dependencies:
    dart_openapi_generator: ^0.1.0
    build_runner: ^2.4.0
  

  dart_openapi_generator_annotations is a runtime dependency — it provides the @OpenApiGenerator annotation your trigger file imports. dart_openapi_generator and build_runner are dev-only.

• Place your OpenAPI spec

  Copy your OpenAPI 3.x spec (YAML or JSON) into your project, for example at openapi/api.yaml. The path is relative to your pubspec.yaml.

  OpenAPI 3.0, 3.1, and 3.2 are all supported. Swagger 2.x is not supported.
• Add the annotation

  In any Dart file (conventionally lib/main.dart), import the annotations package and place @OpenApiGenerator on a class:

  lib/main.dart

  import 'package:dart_openapi_generator_annotations/dart_openapi_generator_annotations.dart';
  
  @OpenApiGenerator(
    inputSpec: LocalSpec('openapi/api.yaml'),
    outputDir: 'lib/generated',
    clientName: 'MyApiClient',
  )
  class $MyApp {}
  

  inputSpec and outputDir are the only required fields. See Annotation Reference for all fields and their defaults.

• Run code generation

  dart run build_runner build
  

  Use dart run build_runner watch to automatically regenerate when your spec changes.

  After generation, lib/generated/ will contain:

  • api_client.dart — the MyApiClient aggregator class
  • models/ — one .dart file per schema, in alphabetical order
  • services/ — one .dart file per OpenAPI tag, in alphabetical order
  • generated.dart — a barrel that exports every generated file
• Import the barrel

  Import the single barrel export so all generated types are available:

  lib/main.dart

  import 'generated/generated.dart';
  

• Instantiate the client

  Create your client. If baseUrl is omitted, the URL from servers[0] in your spec is used.

  final client = MyApiClient(
    baseUrl: 'https://api.example.com/v1',
  );
  
  // Call any generated service method:
  final users = await client.users.listUsers();
  

  The constructor also accepts dio (inject a pre-configured Dio instance), interceptors, connectTimeout, and receiveTimeout.

• Add authentication (optional)

  If your spec declares securitySchemes, the generator emits static auth-helper factories on the client class. Pass the factory's return value via interceptors::

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

  Available factories depend on which security scheme types appear in your spec. See Advanced — Authentication for Bearer, API key, and Basic auth.

What's next?

• Annotation Reference — full documentation of every @OpenApiGenerator field
• Generated Code — understand every generated file type
• Advanced — remote specs, auth schemes, cleanOutput, dateTimeConverter, caching, and OpenAPI 3.2