This library is the dart/flutter implementation of openapi client sdk code generation.

With this library, you can generate openapi client sdk libraries from your openapi specification right in your flutter/dart projects. (see example)

To be used together with openapi-generator-annotations

Usage

Include openapi-generator-annotations as a dependency in the dependencies section of your pubspec.yaml file :

dependencies:
  openapi_generator_annotations: ^4.11.0

Add openapi-generator in the dev dependencies section of your pubspec.yaml file:

dev_dependencies:
  openapi_generator: ^4.11.0

Annotate a dart class with @Openapi() annotation

@Openapi(
    additionalProperties:
    AdditionalProperties(pubName: 'petstore_api', pubAuthor: 'Johnny dep'),
    inputSpecFile: 'example/openapi-spec.yaml',
    generatorName: Generator.dart,
    outputDirectory: 'api/petstore_api')
class Example extends OpenapiGeneratorConfig {}

Run command below to generate open api client sdk from spec file specified in annotation.

flutter pub run build_runner build --delete-conflicting-outputs

The api sdk will be generated in the folder specified in the annotation. See examples for more details

Next Generation

As of version 5.0 of this library, there is some new functionality that has been added to the generator. This version will have the ability to:

• cache changes in the openapi spec
• Rerun when there ares difference in the cached copy and current copy
• Pull from a remote source and cache that.
  • Note: This means that your cache could be potentially stale. But in that case this flow will still pull the latest and run.
  • While this is a possible usage, if you are actively developing your spec it is preferred you provide a local copy.
• Skip generation based off:
  • Flags
  • No difference between the cache and local
• And all the functionality provided previously.

Your original workflow stay the same but there is a slight difference in the annotations.

New:

@Openapi(
  additionalProperties:
  DioProperties(pubName: 'petstore_api', pubAuthor: 'Johnny dep..'),
  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 {}

Known Issues

Dependency issues/conflicts

This is not an issue with this library but with flutter/dart in general. If you are having issues with dependencies, what you can do is make use of dependency overrides. This is added to the pubspec.yaml of the generated package and then the pubspec must be added to the .openapi-generator-ignore of the generated package. For example, let's assume you want to override the analyzer package for the generated source

in generatedsource/pubspec.yaml add the following

dependency_overrides:
  analyzer: 1.0.0

Then in generatedsources/.openapi-generator-ignore, add the below so that the pubspec is not overwritten next time you run source gen

pubspec.yaml

The above steps are useful when you have issues with dependency conflicts, clashes. You can even use it to upgrade the library packages in the generated source.

FAQ

Q: I run source gen (flutter pub run build_runner build --delete-conflicting-outputs), The api generator does not run.

A: The source generator of flutter only runs when there are changes to the file that has the annotation. If this ever happens, just go to the file that has the @openapi annotation and edit something in the file.

Q: How do I prevent files from being generated e.g tests

A: To prevent any files from being generated, you need to add it to .openapi-generator-ignore. This file is in the root of the generated code. For example, to prevent generating tests, add test/* to the file.

Features and bugs

Please file feature requests and bugs at the issue tracker.

Running Tests

Requirements:

• Docker