openapi_generator

Description:

openapi generator

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
copied to clipboard
Add openapi-generator in the dev dependencies section of your pubspec.yaml
file:
dev_dependencies:
openapi_generator: ^4.11.0
copied to clipboard
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 {}
copied to clipboard
Run command below to generate open api client sdk from spec file specified in annotation.
flutter pub run build_runner build --delete-conflicting-outputs
copied to clipboard
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 {}
copied to clipboard
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
copied to clipboard
Then in generatedsources/.openapi-generator-ignore, add the below so that the pubspec is not overwritten next time you
run source gen
pubspec.yaml
copied to clipboard
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:

Identify the files with the bad code and manually correct them.
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
copied to clipboard
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