Merge pull request #96 from Nexushunter/generate-for-spec-changes

feat: Generator generates sources only when changes are made to spec (remote or local)

.github/workflows/code_quality.yml

@@ -11,6 +11,32 @@ on:
  workflow_dispatch:
 
 jobs:
+ ci:
+ name: Dart CI Checks
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ work_dir: [ openapi-generator, openapi-generator-annotations ]
+ defaults:
+ run:
+ working-directory: ${{ matrix.work_dir }}
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+ - name: Setup Dart
+ uses: dart-lang/setup-dart@v1.5.0
+ with:
+ sdk: stable
+ - name: Install Dependencies
+ run: dart pub get
+ - name: Validate formatting
+ run: dart format ./ --set-exit-if-changed
+ - name: Run analyzer
+ run: dart analyze --fatal-warnings
+ - name: Run tests
+ run: dart test
+
  build:
  name: Build example project 🛠️
  runs-on: ubuntu-latest
@@ -33,20 +59,21 @@ jobs:
  - run: flutter pub run build_runner build --delete-conflicting-outputs
  - run: flutter build apk
 
-# - name: Upload artifact (Client) ⬆️💻
-# uses: actions/upload-artifact@v3.1.1
-# with:
-# name: example
-# path: |
-# example/build/web
+ # - name: Upload artifact (Client) ⬆️💻
+ # uses: actions/upload-artifact@v3.1.1
+ # with:
+ # name: example
+ # path: |
+ # example/build/web
 
  pr_context:
  name: Save PR context as artifact
  if: ${{ always() && !cancelled() && github.event_name == 'pull_request' }}
  runs-on: ubuntu-latest
  needs:
-# - dependency-review
+ # - dependency-review
  - build
+ - ci
 
  steps:
  - name: Save PR context

README.md

@@ -4,6 +4,15 @@
 
 This codebase houses the dart/flutter implementations of the openapi client sdk code generation libraries.
 
+## TOC
+
+- [Introduction](#introduction)
+- [Usage](#usage)
+- [NextGen](#next-generation)
+- [Features & Bugs](#features-and-bugs)
+
+## Introduction
+
 With this project, you can generate openapi client sdk libraries for your openapi specification right in your
 flutter/dart projects. (see example)
 
@@ -17,37 +26,42 @@ This repo contains the following dart libraries
 | openapi-generator-annotations | Annotations for annotating dart class with instructions for generating openapi sdk [see here for usage](https://pub.dev/packages/openapi_generator_annotations) | [![pub package](https://img.shields.io/pub/v/openapi_generator_annotations.svg)](https://pub.dev/packages/openapi_generator) |
 | openapi-generator-cli | Cli code openapi sdk generator for dart [see here for usage](https://pub.dev/packages/openapi_generator_cli) | [![pub package](https://img.shields.io/pub/v/openapi_generator_cli.svg)](https://pub.dev/packages/openapi_generator_cli) |
 
-
-
 ## Usage
 
-Include [openapi-generator-annotations](https://pub.dev/packages/openapi_generator_annotations) as a dependency in the dependencies section of your pubspec.yaml file :
+Include [openapi-generator-annotations](https://pub.dev/packages/openapi_generator_annotations) as a dependency in the
+dependencies section of your pubspec.yaml file :
 
 ```yaml
 dependencies:
  openapi_generator_annotations: ^[latest-version]
 ```
-For testing out the beta features in openapi generator, use the beta branch like below. This is not recommended for production builds
+
+For testing out the beta features in openapi generator, use the beta branch like below. This is not recommended for
+production builds
+
 ```yaml
 dependencies:
- openapi_generator_annotations: 
+ openapi_generator_annotations:
  git:
  url: https://github.com/gibahjoe/openapi-generator-dart.git
  ref: beta
  path: openapi-generator-annotations
 ```
 
-
-Add [openapi-generator](https://pub.dev/packages/openapi_generator) in the dev dependencies section of your pubspec.yaml file:
+Add [openapi-generator](https://pub.dev/packages/openapi_generator) in the dev dependencies section of your pubspec.yaml
+file:
 
 ```yaml
 dev_dependencies:
  openapi_generator: ^[latest version]
 ```
-For testing out the beta features in openapi generator, use the beta branch like below. This is not recommended for production builds
+
+For testing out the beta features in openapi generator, use the beta branch like below. This is not recommended for
+production builds
+
 ```yaml
 dev_dependencies:
- openapi_generator: 
+ openapi_generator:
  git:
  url: https://github.com/gibahjoe/openapi-generator-dart.git
  ref: beta
@@ -66,17 +80,62 @@ Annotate a dart class with @Openapi() annotation
 class Example extends OpenapiGeneratorConfig {}
 ```
 
-Run 
+Run
+
 ```shell
 dart run build_runner build --delete-conflicting-outputs
 ```
+
 or
+
 ```shell
 flutter pub run build_runner build --delete-conflicting-outputs
 ```
+
 to generate open api client sdk from spec file specified in annotation.
 The api sdk will be generated in the folder specified in the annotation. See examples for more details
 
+## Next Generation
+
+There is some new functionality slated to be added to the generator. This version will have the ability to:
+
+- cache changes in the OAS 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:
+
+```dart
+@Openapi(
+ additionalProperties:
+ AdditionalProperties(pubName: 'petstore_api', pubAuthor: 'Johnny dep'),
+ inputSpecFile: 'example/openapi-spec.yaml',
+ generatorName: Generator.dart,
+ outputDirectory: 'api/petstore_api',
+ cachePath: 'some/preferred/directory/cache.json',
+ useNextGen: true
+)
+class Example extends OpenapiGeneratorConfig {}
+```
+
+**IMPORTANT** With the new changes comes 2 new annotation properties:
+
+- useNextGen (boolean)
+ - Default: `false`
+- cachePath (String)
+ - Default: `.dart_tool/openapi-generator-cache.json`
+ - Must be a path to a `json` file.
+ - Can only be set when `useNextGen` is `true`
+
 ## Features and bugs
 
 Please file feature requests and bugs at the [issue tracker][tracker].

example/.gitignore

@@ -44,5 +44,5 @@ app.*.map.json
 /android/app/debug
 /android/app/profile
 /android/app/release
-api
+api/petstore_api/**
 !api/petstore_api/pubspec.yaml

example/api/petstore_api/pubspec.yaml

@@ -0,0 +1,19 @@
+name: petstore_api
+version: 1.0.0
+description: OpenAPI API client
+homepage: homepage
+
+environment:
+ sdk: '>=2.15.0 <3.0.0'
+
+dependencies:
+ dio: '^5.0.0'
+ one_of: '>=1.5.0 <2.0.0'
+ one_of_serializer: '>=1.5.0 <2.0.0'
+ built_value: '>=8.4.0 <9.0.0'
+ built_collection: '>=5.1.1 <6.0.0'
+
+dev_dependencies:
+ built_value_generator: '>=8.4.0 <9.0.0'
+ build_runner: any
+ test: ^1.16.0

example/lib/main.dart

@@ -6,14 +6,15 @@ void main() {
 }
 
 @Openapi(
- additionalProperties:
- DioProperties(pubName: 'petstore_api', pubAuthor: 'Johnny dep..'),
- inputSpecFile: 'openapi-spec.yaml',
- typeMappings: {'Pet': 'ExamplePet'},
- generatorName: Generator.dio,
- runSourceGenOnOutput: true,
- alwaysRun: true,
- outputDirectory: 'api/petstore_api')
+ additionalProperties:
+ DioProperties(pubName: 'petstore_api', pubAuthor: 'Johnny dep..'),
+ inputSpecFile: 'openapi-spec.yaml',
+ typeMappings: {'Pet': 'ExamplePet'},
+ generatorName: Generator.dio,
+ runSourceGenOnOutput: true,
+ alwaysRun: true,
+ outputDirectory: 'api/petstore_api',
+)
 class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);
 

openapi-generator-annotations/analysis_options.yaml

@@ -1,8 +1,3 @@
-# Defines a default set of lint rules enforced for
-# projects at Google. For details and rationale,
-# see https://github.com/dart-lang/pedantic#enabled-lints.
-include: package:pedantic/analysis_options.yaml
-
 # For lint rules and documentation, see http://dart-lang.github.io/linter/lints.
 # Uncomment to specify additional rules.
 # linter:

openapi-generator-annotations/example/example.dart

@@ -5,5 +5,7 @@ import 'package:openapi_generator_annotations/openapi_generator_annotations.dart
  AdditionalProperties(pubName: 'petstore_api', pubAuthor: 'Johnny dep'),
  inputSpecFile: 'example/openapi-spec.yaml',
  generatorName: Generator.dio,
- outputDirectory: 'api/petstore_api')
+ outputDirectory: 'api/petstore_api',
+ // useNextGen: true,
+ cachePath: 'something')
 class Example extends OpenapiGeneratorConfig {}