From c16cd27938d66aad08a6d67493eaa832e13e128e Mon Sep 17 00:00:00 2001 From: Gibah Joseph Date: Tue, 5 Nov 2024 21:46:06 +0000 Subject: [PATCH] chore: cleaned up tests, updated docs and prepared for final release --- .github/workflows/release.yml | 26 ++---- .../openapi_generator_annotations_base.dart | 13 ++- openapi-generator-annotations/pubspec.yaml | 2 + .../openapi_generator_annotations_test.dart | 7 +- openapi-generator/README.md | 82 +++++++++++-------- openapi-generator/pubspec.yaml | 6 +- 6 files changed, 72 insertions(+), 64 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 6e52c45..1ef41c9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,22 +15,10 @@ jobs: runs-on: ubuntu-latest needs: [test] steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Setup Dart - uses: dart-lang/setup-dart@v1 - - - name: Install Melos - run: dart pub global activate melos - - - name: Authenticate with Pub - run: echo "${{ secrets.PUB_CREDENTIAL_JSON }}" > ~/.pub-cache/credentials.json - - - name: Bootstrap Melos - run: melos bootstrap - - - name: Version and Publish - run: | - melos version --yes - melos publish --no-dry-run --yes + - uses: actions/checkout@v4 + - uses: dart-lang/setup-dart@v1 + - uses: bluefireteam/melos-action@v3 + - name: Authenticate with Pub + run: echo "${{ secrets.PUB_CREDENTIAL_JSON }}" > ~/.pub-cache/credentials.json + - name: Publish + run: melos publish --no-dry-run --yes diff --git a/openapi-generator-annotations/lib/src/openapi_generator_annotations_base.dart b/openapi-generator-annotations/lib/src/openapi_generator_annotations_base.dart index 5e8278d..56d4e22 100644 --- a/openapi-generator-annotations/lib/src/openapi_generator_annotations_base.dart +++ b/openapi-generator-annotations/lib/src/openapi_generator_annotations_base.dart @@ -143,15 +143,14 @@ class Openapi { /// Defaults to [false]. final bool forceAlwaysRun; - /// Skips execution if the OpenAPI specification file is older than the output folder. + /// Skips execution if the OpenAPI specification file is different from a cached copy. /// /// For remote specifications, the file will be downloaded and cached locally. /// The cache is then compared to the remote file to detect any changes. /// - /// **Default behavior:** - /// - If [inputSpec] is a [RemoteSpec], this is set to `true`, meaning execution will be skipped if no changes are detected. - /// - For all other cases, this is set to `false`. - + /// If set to false, a cached copy of the OpenAPI specification file is not kept. + /// + /// Defaults to [true]. final bool skipIfSpecIsUnchanged; const Openapi({ @@ -175,8 +174,8 @@ class Openapi { this.projectPubspecPath, this.debugLogging = false, this.forceAlwaysRun = true, - bool? skipIfSpecIsUnchanged, - }) : skipIfSpecIsUnchanged = skipIfSpecIsUnchanged ?? inputSpec is RemoteSpec; + this.skipIfSpecIsUnchanged = true, + }); @override String toString() { diff --git a/openapi-generator-annotations/pubspec.yaml b/openapi-generator-annotations/pubspec.yaml index b2ce713..b519e9a 100644 --- a/openapi-generator-annotations/pubspec.yaml +++ b/openapi-generator-annotations/pubspec.yaml @@ -8,6 +8,8 @@ environment: sdk: '>=2.12.0 <4.0.0' dependencies: + crypto: '>=3.0.6 <=4.0.0' + meta: '>=1.16.0 <=2.0.0' dev_dependencies: test: diff --git a/openapi-generator-annotations/test/openapi_generator_annotations_test.dart b/openapi-generator-annotations/test/openapi_generator_annotations_test.dart index 5042d05..aa2e146 100644 --- a/openapi-generator-annotations/test/openapi_generator_annotations_test.dart +++ b/openapi-generator-annotations/test/openapi_generator_annotations_test.dart @@ -13,7 +13,7 @@ void main() { generatorName: Generator.dart, ); expect(props.additionalProperties, isNull); - expect(props.skipSpecValidation, false); + expect(props.skipSpecValidation, isFalse); expect(props.inputSpec.path, InputSpec.json().path); expect(props.templateDirectory, isNull); expect(props.generatorName, Generator.dart); @@ -23,12 +23,13 @@ void main() { expect(props.reservedWordsMappings, isNull); expect(props.inlineSchemaNameMappings, isNull); expect(props.apiPackage, isNull); - expect(props.fetchDependencies, true); - expect(props.runSourceGenOnOutput, true); + expect(props.fetchDependencies, isTrue); + expect(props.runSourceGenOnOutput, isTrue); expect(props.cachePath, isNull); expect(props.projectPubspecPath, isNull); expect(props.debugLogging, isFalse); expect(props.nameMappings, isNull); + expect(props.skipIfSpecIsUnchanged, isTrue); }); group('NextGen', () { test('Sets cachePath', () { diff --git a/openapi-generator/README.md b/openapi-generator/README.md index 59c7a86..a216f83 100755 --- a/openapi-generator/README.md +++ b/openapi-generator/README.md @@ -11,7 +11,7 @@ To be used together with [openapi-generator-annotations](https://pub.dev/package 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**: _duh!!!_ Just to download the openapi jar initially. Once it is cached, you are good to go. +2. **Internet Connection**: _duh!!!_ Just to download the openapi jar initially. Once it is cached, you are good to go. ## Usage @@ -31,16 +31,20 @@ dev_dependencies: openapi_generator: ^latest ``` -Annotate a dart class with @Openapi() annotation +Annotate any dart class with @Openapi() annotation ```dart @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 {} + 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. @@ -51,40 +55,52 @@ 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 +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: -- 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. +- `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`. -Your original workflow stay the same but there is a slight difference in the annotations. +## Usage (pre 5.0.0 versions) -New: +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 +``` + +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 +``` + +Annotate any dart class with @Openapi() annotation ```dart @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 {} + 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. + +```cmd +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 diff --git a/openapi-generator/pubspec.yaml b/openapi-generator/pubspec.yaml index 339a0ee..8c585a8 100755 --- a/openapi-generator/pubspec.yaml +++ b/openapi-generator/pubspec.yaml @@ -10,9 +10,11 @@ dependencies: build: '>=1.0.0 <=3.0.0' source_gen: '>=1.0.0 <=2.0.0' path: '>=1.0.0 <=2.0.0' - openapi_generator_annotations: '5.0.2' + openapi_generator_annotations: ^6.0.0 analyzer: '>=2.0.0 <7.0.0' - openapi_generator_cli: '>5.0.2 <7.0.0' + openapi_generator_cli: ^6.0.0 + crypto: '>=3.0.6 <=4.0.0' + meta: '>=1.16.0 <=2.0.0' yaml: ^3.1.2 http: '>=0.13.1 <=2.0.0' logging: '>=1.0.0 <=2.0.0'