openapi_generator 5.0.2

openapi_generator: ^5.0.2 copied to clipboard

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.

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