openapi_generator_annotations

openapi-generator-dart

Like this library? Give us a star or a like!

---

⚠️ Java Requirement

Java is required to use this library.
The OpenAPI Generator CLI is a Java application.
Please ensure you have Java (version 8 or higher) installed and available in your system PATH.
You can check your Java installation with:

java -version

If you do not have Java installed, download it from Adoptium or Oracle.

---

⚠️ Deprecation & Breaking Change Notice

skipIfSpecIsUnchanged is Deprecated

• The skipIfSpecIsUnchanged option is now deprecated and will be removed in the next major release.
• Local OpenAPI specs are now automatically watched for changes.
  • If your spec file is in the lib/ folder, this works out of the box.
  • If your spec file is outside lib/, you must update or add a build.yaml to include your spec file as a source.
    Example:

    targets:
      $default:
        sources:
          - $package$
          - lib/**
          - openapi.yaml # or your spec file path
    

• Remote specs:
  Use the forceAlwaysRun (defaults to false) option to ensure the generator always runs.
  • This option is ignored for local specs.
  • When enabled, it modifies the annotated file to force regeneration. This might cause issues such as merge conflicts

---

Overview

This repository provides Dart/Flutter libraries for generating OpenAPI client SDKs directly from your OpenAPI specification. Inspired by Openapi Generator Cli (npm), it enables seamless integration into Dart and Flutter projects.

Libraries

Library	Description	Latest Version
openapi-generator	Dev dependency for generating OpenAPI client SDK via Dart source gen (usage)
openapi-generator-annotations	Annotations for configuring OpenAPI client SDK generation (usage)
openapi-generator-cli	CLI wrapper for OpenAPI code generation (usage)

---

Quick Start

1. Add Dependencies

Add the annotations package to your pubspec.yaml:

dependencies:
  openapi_generator_annotations: ^<latest-version>

Add the generator as a dev dependency:

dev_dependencies:
  openapi_generator: ^<latest-version>

Beta Features:
For beta features, use the beta branch:

dependencies:
  openapi_generator_annotations:
    git:
      url: https://github.com/gibahjoe/openapi-generator-dart.git
      ref: beta
      path: openapi-generator-annotations

dev_dependencies:
  openapi_generator:
    git:
      url: https://github.com/gibahjoe/openapi-generator-dart.git
      ref: beta
      path: openapi-generator

2. Annotate Your Dart Class

Annotate a Dart class with @Openapi() to configure code generation:

import 'package:openapi_generator_annotations/openapi_generator_annotations.dart';

@Openapi(
  additionalProperties: DioProperties(pubName: 'petstore_api', pubAuthor: 'Johnny Depp'),
  inputSpec: RemoteSpec(path: 'https://petstore3.swagger.io/api/v3/openapi.json'),
  typeMappings: {'Pet': 'ExamplePet'},
  generatorName: Generator.dio,
  runSourceGenOnOutput: true,
  outputDirectory: 'api/petstore_api',
)
class Example {}

3. Generate the SDK

Run the build command:

dart run build_runner build --delete-conflicting-outputs
# or, for Flutter projects:
flutter pub run build_runner build --delete-conflicting-outputs

The generated SDK will appear in the specified output directory.

---

Next Generation Features (v5.0+)

• Spec Caching: Automatically caches your OpenAPI spec for faster incremental builds.
• Remote Spec Support: Pulls and caches remote specs; always fetches the latest version unless using a local copy.
• Smart Generation: Skips code generation if there are no changes in the spec or based on flags.
• All previous features remain available.

Example:

@Openapi(
  additionalProperties: DioProperties(pubName: 'petstore_api', pubAuthor: 'Johnny Depp'),
  inputSpec: RemoteSpec(path: 'https://petstore3.swagger.io/api/v3/openapi.json'),
  typeMappings: {'Pet': 'ExamplePet'},
  generatorName: Generator.dio,
  runSourceGenOnOutput: true,
  outputDirectory: 'api/petstore_api',
)
class Example {}

---

Advanced Configuration

If you are having issues with the generated code, this is not an problem with this package and creating an issue here will not help solve it. Its best to create the issue in the base OpenApi library since this package is a wrapper around that library for ease of use with Flutter/dart.

Below are some advanced configurations you may try.

• Custom Templates:
  Use the templateDirectory parameter to specify a custom code generation template.

• Type & Import Mappings:
  Use typeMappings and importMappings to control how OpenAPI types and models are mapped in Dart.

• Reserved Words:
  Use reservedWordsMappings to avoid conflicts with Dart reserved words.

Example:

@Openapi(
  additionalProperties: DioProperties(pubName: 'custom_api', pubAuthor: 'Jane Doe'),
  inputSpec: InputSpec(path: 'openapi-spec.yaml'),
  generatorName: Generator.dio,
  templateDirectory: 'templates/dart',
  typeMappings: {'date': 'DateTime'},
  importMappings: {'DateTime': 'package:my_project/date_time.dart'},
  reservedWordsMappings: {'class': 'clazz'},
  outputDirectory: 'api/custom_api',
)
class CustomApi {}

---

Troubleshooting

Common Issues

• Dependency Conflicts:
  Use dependency_overrides in the generated package's pubspec.yaml and add pubspec.yaml to .openapi-generator-ignore to prevent overwrites.

• Incorrect Generated Code:

  • Fix your OpenAPI spec (preferred).
  • Manually edit the generated code and add the files to .openapi-generator-ignore to prevent them from being overwritten.

.openapi-generator-ignore Example:

# Ignore all test files
test/*
# Ignore pubspec.yaml to preserve manual changes
pubspec.yaml