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

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

Author: gibahjoe

.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/[email protected]
+        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/[email protected]
-#        with:
-#          name: example
-#          path: |
-#            example/build/web
+  #      - name: Upload artifact (Client) ⬆️💻
+  #        uses: actions/[email protected]
+  #        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 {}