docs: updated known issues doc

Author: gibahjoe

README.md

@@ -134,6 +134,9 @@ New:
 class Example {}
 ```
 
+## Known Issues
+
+Check out the known issues article here [Known Issues](openapi-generator-annotations/README.md#known-issues)
 
 ## Contributing
 

example/lib/main.dart

@@ -1,4 +1,4 @@
-// Openapi Generator last run: : 2024-01-16T01:49:21.940229
+// Openapi Generator last run: : 2024-01-16T03:54:39.346434
 import 'package:flutter/material.dart';
 import 'package:openapi_generator_annotations/openapi_generator_annotations.dart';
 

openapi-generator-annotations/README.md

@@ -53,24 +53,8 @@ Give a thumbs up if you like this library
 
 
 ## 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
-```yaml
-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
-```.gitignore
-pubspec.yaml
-```
-
-The above steps are usefull when you have issues with dependency conflicts, clashes. You can even use it to upgrade the
-library packages in the generated source.
+Check out the known issues article here [Known Issues](../openapi-generator-annotations/README.md#known-issues)
 
 ## Features and bugs
 

openapi-generator-cli/README.md

@@ -51,6 +51,10 @@ pubspec.yaml
 The above steps are usefull when you have issues with dependency conflicts, clashes. You can even use it to upgrade the
 library packages in the generated source.
 
+## Known Issues
+
+Check out the known issues article here [Known Issues](../openapi-generator-annotations/README.md#known-issues)
+
 ## Contributing
 
 Please read our [Contributing guidelines](../CONTRIBUTING.md) before submitting a Pull Request.

openapi-generator/README.md

@@ -45,6 +45,40 @@ 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:
+
+```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 {}
+```
+
 ## Known Issues
 
 ### Dependency issues/conflicts
@@ -73,14 +107,48 @@ 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.
 
-## FAQ
+### Resolving Issues with Generated Code
+
+This library is a wrapper around [openapi generator](https://github.com/OpenAPITools/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:
 
-Q: I run source gen (`flutter pub run build_runner build --delete-conflicting-outputs`), The api generator does not run.
+#### 1. Correct the OpenAPI Documentation
 
-A: The source generator of flutter only runs when there are changes to the file that has the annotation. If this ever
-happens, just go to the file that has the `@openapi` annotation and edit something in the file.
+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.
+
+```gitignore
+# 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
+#### 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.

openapi-generator/lib/src/builder.dart

@@ -1,7 +1,8 @@
 import 'package:build/build.dart';
 import 'package:openapi_generator/src/openapi_generator_runner.dart';
+import 'package:openapi_generator/src/process_runner.dart';
 import 'package:source_gen/source_gen.dart';
 
 Builder openApiClientSdk(BuilderOptions options) =>
-    LibraryBuilder(OpenapiGenerator(),
+    LibraryBuilder(OpenapiGenerator(ProcessRunner()),
         generatedExtension: '.openapi_generator');

openapi-generator/lib/src/models/generator_arguments.dart

@@ -155,7 +155,7 @@ class GeneratorArguments {
   FutureOr<List<String>> get jarArgs async => [
         'generate',
         if (outputDirectory?.isNotEmpty ?? false) '-o=$outputDirectory',
-        '-i=${await inputFileOrFetch}',
+        '-i=$inputFileOrFetch',
         if (templateDirectory?.isNotEmpty ?? false) '-t=$templateDirectory',
         '-g=$generatorName',
         if (skipValidation) '--skip-validate-spec',

openapi-generator/lib/src/openapi_generator_runner.dart

@@ -9,6 +9,7 @@ import 'package:logging/logging.dart';
 import 'package:openapi_generator/src/determine_flutter_project_status.dart';
 import 'package:openapi_generator/src/gen_on_spec_changes.dart';
 import 'package:openapi_generator/src/models/output_message.dart';
+import 'package:openapi_generator/src/process_runner.dart';
 import 'package:openapi_generator/src/utils.dart';
 import 'package:openapi_generator_annotations/openapi_generator_annotations.dart'
     as annots;
@@ -18,10 +19,9 @@ import 'models/command.dart';
 import 'models/generator_arguments.dart';
 
 class OpenapiGenerator extends GeneratorForAnnotation<annots.Openapi> {
-  @Deprecated('To be removed in next major version')
-  final bool testMode;
+  final ProcessRunner _processRunner;
 
-  OpenapiGenerator({this.testMode = false});
+  OpenapiGenerator(this._processRunner);
 
   @override
   FutureOr<String> generateForAnnotatedElement(
@@ -98,21 +98,17 @@ class OpenapiGenerator extends GeneratorForAnnotation<annots.Openapi> {
     var javaOpts = Platform.environment['JAVA_OPTS'] ?? '';
 
     ProcessResult result;
-    if (!testMode) {
-      result = await Process.run(
-        'java',
-        [
-          if (javaOpts.isNotEmpty) javaOpts,
-          '-jar',
-          binPath,
-          ...args,
-        ],
-        workingDirectory: Directory.current.path,
-        runInShell: Platform.isWindows,
-      );
-    } else {
-      result = ProcessResult(999999, 0, null, null);
-    }
+    result = await _processRunner.run(
+      'java',
+      [
+        if (javaOpts.isNotEmpty) javaOpts,
+        '-jar',
+        binPath,
+        ...args,
+      ],
+      workingDirectory: Directory.current.path,
+      runInShell: Platform.isWindows,
+    );
 
     if (result.exitCode != 0) {
       return Future.error(
@@ -342,16 +338,12 @@ class OpenapiGenerator extends GeneratorForAnnotation<annots.Openapi> {
     );
 
     ProcessResult results;
-    if (!testMode) {
-      results = await Process.run(
-        command.executable,
-        command.arguments,
-        runInShell: Platform.isWindows,
-        workingDirectory: args.outputDirectory,
-      );
-    } else {
-      results = ProcessResult(99999, 0, null, null);
-    }
+    results = await _processRunner.run(
+      command.executable,
+      command.arguments,
+      runInShell: Platform.isWindows,
+      workingDirectory: args.outputDirectory,
+    );
 
     if (results.exitCode != 0) {
       return Future.error(
@@ -398,16 +390,12 @@ class OpenapiGenerator extends GeneratorForAnnotation<annots.Openapi> {
       );
 
       ProcessResult results;
-      if (!testMode) {
-        results = await Process.run(
-          command.executable,
-          command.arguments,
-          runInShell: Platform.isWindows,
-          workingDirectory: args.outputDirectory,
-        );
-      } else {
-        results = ProcessResult(999999, 0, null, null);
-      }
+      results = await _processRunner.run(
+        command.executable,
+        command.arguments,
+        runInShell: Platform.isWindows,
+        workingDirectory: args.outputDirectory,
+      );
 
       if (results.exitCode != 0) {
         return Future.error(
@@ -482,16 +470,13 @@ class OpenapiGenerator extends GeneratorForAnnotation<annots.Openapi> {
   Future<void> formatCode({required GeneratorArguments args}) async {
     final command = Command(executable: 'dart', arguments: ['format', './']);
     ProcessResult result;
-    if (!testMode) {
-      result = await Process.run(
-        command.executable,
-        command.arguments,
-        workingDirectory: args.outputDirectory,
-        runInShell: Platform.isWindows,
-      );
-    } else {
-      result = ProcessResult(99999, 0, null, null);
-    }
+
+    result = await _processRunner.run(
+      command.executable,
+      command.arguments,
+      workingDirectory: args.outputDirectory,
+      runInShell: Platform.isWindows,
+    );
 
     if (result.exitCode != 0) {
       return Future.error(

openapi-generator/lib/src/process_runner.dart

@@ -0,0 +1,13 @@
+import 'dart:io';
+
+class ProcessRunner {
+  Future<ProcessResult> run(String executable, List<String> arguments,
+      {Map<String, String>? environment,
+      String? workingDirectory,
+      bool runInShell = false}) {
+    return Process.run(executable, arguments,
+        environment: environment,
+        workingDirectory: workingDirectory,
+        runInShell: runInShell);
+  }
+}

openapi-generator/pubspec.yaml

@@ -20,6 +20,8 @@ dependencies:
 
 dev_dependencies:
   test: ^1.24.2
+  mockito: ^5.4.4
+  test_process:
   build_test: '>=1.2.0 <3.0.0'
   source_gen_test:
   pedantic: