openapi_generator 6.0.0

Generator for openapi client sdk inspired by the npm implementation of openapi-generator-cli.

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

Requirements

1. Java: You must have java installed on your system for this library to work. if you are a developer, chances aare you already. Walking you through how to install Java is beyond the scope of this project.
2. Internet Connection: duh!!! Just to download the openapi jar initially. Once it is cached, you are good to go.

Usage

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

dependencies:
  openapi_generator_annotations: ^latest

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

dev_dependencies:
  openapi_generator: ^latest

Annotate any dart class with @Openapi() annotation

@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 {}

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

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

• skipIfSpecUnchanged: Set to false if you want the library to generate the client SDK each time, even without changes in the OpenAPI spec. Defaults to true.
• forceAlwaysRun (Breaking Change): Forces build_runner to detect changes by marking the annotated file. May cause merge conflicts in team environments, so it defaults to false.

Usage (pre 5.0.0 versions)

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

dependencies:
   openapi_generator_annotations: ^latest

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

dev_dependencies:
   openapi_generator: ^latest

Annotate any 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

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: <-- preferred version -->

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.

Resolving Issues with Generated Code

This library is a wrapper around openapi generator to enable seamless (kind of) integration into dart's build system. The underlying generator itself is not 100% perfect mainly because it is multipurpose built and sometimes generates bad code due to various reasons including incorrect openapi doc. If you encounter issues with the code generated by the OpenAPI generator, there are two main ways to resolve them:

1. Correct the OpenAPI Documentation

The issue might be due to incorrect or conflicting OpenAPI documentation. For instance, if a model name conflicts with Dart's reserved names, you should edit the OpenAPI documentation to fix the issue.

2. Manually Fix the Generated Code

If correcting the OpenAPI documentation is not possible or you don't have access to it, you can manually fix the generated code.

Here are the steps to take to do this:

1. Identify the files with the bad code and manually correct them.
2. Add the manually edited files to the .openapi-generator-ignore file. This ensures that your changes are not overridden when you run the generator again. below is a sample of the .openapi-generator-ignore file. This file uses the .gitignore syntax and also has documentation in it.

# You can also negate patterns with an exclamation (!).
# For example, you can ignore all files in a docs folder with the file extension .md:
docs/*.md
# Then explicitly reverse the ignore rule for a single file:
!docs/README.md
path/to/corrected.dart

Remember to commit the .openapi-generator-ignore file to your git repository to preserve these changes.

By following these steps, you should be able to resolve issues with the generated code.

FAQ

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