feat: Include Paths Parameter (#422)

Author: Sadhorsephile

swagger_parser/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 1.40.0
+- Add `include_paths` option for filtering endpoints by paths
+
 ## 1.39.2
 - Add `generate_urls_constants` option for generating URL constants for all endpoints
 

swagger_parser/README.md

@@ -159,6 +159,16 @@ swagger_parser:
    - pattern: "\\]"
      replacement: "_"
 
+  # Optional. Set paths to be included on endpoint generation.
+  #
+  # Also supports wildcard paths (e.g. `/path/*/update` or `/path/**`)
+  #
+  # If set, only endpoints with these paths will be included in the generated clients.
+  include_paths:
+    - "/some/concrete/path/{id}"
+    - "/some/wildcard/*/path"
+    - "/another/wildcard/**"
+
   # Optional. Skip parameters with names.
   skipped_parameters:
     - "X-Some-Token"

swagger_parser/lib/src/config/swp_config.dart

@@ -43,6 +43,7 @@ class SWPConfig {
     this.dartMappableConvenientWhen = false,
     this.excludeTags = const <String>[],
     this.includeTags = const <String>[],
+    this.includePaths,
     this.fallbackClient = 'fallback',
     this.mergeOutputs = false,
     this.includeIfNull = false,
@@ -84,6 +85,7 @@ class SWPConfig {
     required this.useMultipartFile,
     required this.excludeTags,
     required this.includeTags,
+    required this.includePaths,
     required this.fallbackClient,
     required this.mergeOutputs,
     required this.dartMappableConvenientWhen,
@@ -311,6 +313,22 @@ class SWPConfig {
       includedTags = List.from(rootConfig!.includeTags);
     }
 
+    final includePaths = yamlMap['include_paths'] as YamlList?;
+    List<String>? includePathsList;
+    if (includePaths != null) {
+      includePathsList = [];
+      for (final p in includePaths) {
+        if (p is! String) {
+          throw const ConfigException(
+            "Config parameter 'include_paths' values must be List of String.",
+          );
+        }
+        includePathsList.add(p);
+      }
+    } else if (rootConfig?.includePaths case final paths?) {
+      includePathsList = List.from(paths);
+    }
+
     final fallbackClient =
         yamlMap['fallback_client'] as String? ?? rootConfig?.fallbackClient;
 
@@ -376,6 +394,7 @@ class SWPConfig {
       inferRequiredFromNullable:
           inferRequiredFromNullable ?? dc.inferRequiredFromNullable,
       useFlutterCompute: useFlutterCompute ?? dc.useFlutterCompute,
+      includePaths: includePathsList ?? dc.includePaths,
       generateUrlsConstants: generateUrlsConstants ?? dc.generateUrlsConstants,
     );
   }
@@ -550,6 +569,15 @@ class SWPConfig {
   /// Endpoints with these tags will not be included in the generated clients.
   final List<String> excludeTags;
 
+  /// {@template include_paths}
+  /// Optional. Set included paths.
+  ///
+  /// Also supports wildcard paths (e.g. `/path/*/update` or `/path/**`)
+  ///
+  /// If set, only endpoints with these paths will be included in the generated clients.
+  /// {@endtemplate}
+  final List<String>? includePaths;
+
   /// DART ONLY
   /// Optional. Set included tags.
   ///
@@ -641,6 +669,7 @@ class SWPConfig {
       excludeTags: excludeTags,
       replacementRulesForRawSchema: replacementRulesForRawSchema,
       includeTags: includeTags,
+      includePaths: includePaths,
       fallbackClient: fallbackClient,
       inferRequiredFromNullable: inferRequiredFromNullable,
     );

swagger_parser/lib/src/parser/config/parser_config.dart

@@ -17,6 +17,7 @@ class ParserConfig {
     this.useXNullable = false,
     this.excludeTags = const <String>[],
     this.includeTags = const <String>[],
+    this.includePaths,
     this.fallbackClient = 'fallback',
     this.inferRequiredFromNullable = false,
   });
@@ -74,6 +75,9 @@ class ParserConfig {
   /// **NOTE: This will override the [excludeTags] if set.**
   final List<String> includeTags;
 
+  ///{@macro include_paths}
+  final List<String>? includePaths;
+
   /// DART ONLY
   /// Optional. Fallback client name for endpoints without tags.
   ///

swagger_parser/lib/src/parser/parser/open_api_parser.dart

@@ -17,6 +17,7 @@ import 'package:swagger_parser/src/parser/model/universal_type.dart';
 import 'package:swagger_parser/src/parser/utils/anchor_registry.dart';
 import 'package:swagger_parser/src/parser/utils/context_stack.dart';
 import 'package:swagger_parser/src/parser/utils/http_utils.dart';
+import 'package:swagger_parser/src/parser/utils/path_match.dart';
 import 'package:swagger_parser/src/parser/utils/type_utils.dart';
 import 'package:yaml/yaml.dart';
 
@@ -596,10 +597,17 @@ class OpenApiParser {
     if (!_definitionFileContent.containsKey(_pathsConst)) {
       return [];
     }
+
+    final includePaths = config.includePaths;
+
     (_definitionFileContent[_pathsConst] as Map<String, dynamic>).forEach((
       path,
       pathValue,
     ) {
+      if (includePaths != null && !matchesPathPattern(path, includePaths)) {
+        return;
+      }
+
       final pathValueMap = pathValue as Map<String, dynamic>;
 
       // global parameters are defined at the path level (i.e. /users/{id})
@@ -1111,7 +1119,9 @@ class OpenApiParser {
       }
     }
 
-    if (config.includeTags.isNotEmpty || config.excludeTags.isNotEmpty) {
+    if (config.includeTags.isNotEmpty ||
+        config.excludeTags.isNotEmpty ||
+        config.includePaths != null) {
       return _filterUsedClasses(dataClasses);
     }
 

swagger_parser/lib/src/parser/utils/path_match.dart

@@ -0,0 +1,62 @@
+/// Checks if the given [path] matches any of the provided [patterns].
+/// Supports wildcard patterns:
+/// - * matches any characters except forward slashes (one path segment)
+/// - ** matches any characters including forward slashes
+///
+/// Some examples:
+/// - 'some/concrete/path/{id}' matches 'some/concrete/path/{id}'
+/// - `/users/*/update` matches `/users/{id}/update`
+/// - `/another/wildcard/*` matches `/another/wildcard/path`
+/// - `/another/wildcard/**` matches `/another/wildcard/long/path`
+/// - `path/**/parts` matches `path/with/several/parts`
+bool matchesPathPattern(String path, List<String> patterns) {
+  const doubleStarStart = '__DOUBLE_STAR_START__';
+  const doubleStarEnd = '__DOUBLE_STAR_END__';
+  for (final pattern in patterns) {
+    final processedPattern = pattern
+        // Replace /** with end marker (to distinguish from single star)
+        .replaceAll(
+          '/**',
+          doubleStarEnd,
+        )
+        // Replace ** with start marker (to distinguish from single star)
+        .replaceAll(
+          '**',
+          doubleStarStart,
+        );
+
+    // Escape all regex special characters
+    var escapedPattern = RegExp.escape(
+      processedPattern,
+    )
+        // Replace end marker of double star with .*
+        .replaceAll(
+          doubleStarEnd,
+          '.*',
+        )
+        // Replace with optional trailing slash with any (0+) characters
+        .replaceAll(
+          doubleStarStart,
+          '(?:/.*)?',
+        )
+        // Replace * with one or more characters except /
+        .replaceAll(
+          r'\*',
+          '([^/]+)',
+        );
+
+    // Special handling for patterns starting with * (but not **)
+    // If pattern starts with *, but not with **, and path starts with /, add / at the beginning
+    if (pattern.startsWith('*') &&
+        !pattern.startsWith('**') &&
+        path.startsWith('/')) {
+      escapedPattern = '/$escapedPattern';
+    }
+
+    final regex = RegExp('^$escapedPattern\$');
+    if (regex.hasMatch(path)) {
+      return true;
+    }
+  }
+  return false;
+}

swagger_parser/test/src/parser/utils/path_match_test.dart

@@ -0,0 +1,110 @@
+import 'package:swagger_parser/src/parser/utils/path_match.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('matchesPathPattern', () {
+    test('exact match without wildcards', () {
+      expect(matchesPathPattern('/api/users', ['/api/users']), isTrue);
+      expect(matchesPathPattern('/api/users/profile', ['/api/users/profile']), isTrue);
+      expect(matchesPathPattern('/exact/path/{id}', ['/exact/path/{id}']), isTrue);
+    });
+
+    test('no match for different paths', () {
+      expect(matchesPathPattern('/api/users', ['/api/posts']), isFalse);
+      expect(matchesPathPattern('/api/users/profile', ['/api/users/settings']), isFalse);
+    });
+
+    test('single asterisk wildcard (*)', () {
+      // Basic single segment match
+      expect(matchesPathPattern('/users/123/update', ['/users/*/update']), isTrue);
+      expect(matchesPathPattern('/api/v1/users', ['/api/*/users']), isTrue);
+
+      // No match when path has more segments
+      expect(matchesPathPattern('/users/123/profile/update', ['/users/*/update']), isFalse);
+      expect(matchesPathPattern('/api/v1/extra/users', ['/api/*/users']), isFalse);
+
+      // Match at different positions
+      expect(matchesPathPattern('/users/123', ['/users/*']), isTrue);
+      expect(matchesPathPattern('/api/123/endpoint', ['/api/*/endpoint']), isTrue);
+    });
+
+    test('double asterisk wildcard (**) - long path', () {
+      expect(matchesPathPattern('/api/service/loyalty/balance/history', ['/api/service/loyalty/**']), isTrue);
+    });
+
+    test('double asterisk wildcard (**) - another', () {
+      expect(matchesPathPattern('/another/wildcard/long/path', ['/another/wildcard/**']), isTrue);
+    });
+
+    test('double asterisk wildcard (**) - parts', () {
+      expect(matchesPathPattern('path/with/several/parts', ['path/**/parts']), isTrue);
+    });
+
+    test('double asterisk wildcard (**) - single', () {
+      expect(matchesPathPattern('/api/single', ['/api/**']), isTrue);
+    });
+
+    test('double asterisk wildcard (**) - wildcard', () {
+      expect(matchesPathPattern('wildcard/path', ['wildcard/**']), isTrue);
+    });
+
+    test('double asterisk wildcard (**) - empty', () {
+      expect(matchesPathPattern('/api', ['/api/**']), isTrue);
+    });
+
+    test('multiple patterns', () {
+      expect(matchesPathPattern('/users/123/update', ['/posts/*/create', '/users/*/update']), isTrue);
+      expect(matchesPathPattern('/api/v1/users', ['/api/v2/users', '/api/v1/*']), isTrue);
+      expect(matchesPathPattern('/api/service/loyalty/balance', ['/api/*/loyalty', '/api/service/**']), isTrue);
+    });
+
+    test('special regex characters in paths', () {
+      // Dots in paths
+      expect(matchesPathPattern('/api/v1.0/users', ['/api/*/users']), isTrue);
+      expect(matchesPathPattern('/files/document.pdf', ['/files/*']), isTrue);
+
+      // Plus signs
+      expect(matchesPathPattern('/api/v1+users', ['/api/*']), isTrue);
+
+      // Parentheses
+      expect(matchesPathPattern('/api(v1)', ['/*']), isTrue);
+    });
+
+    test('empty and edge cases', () {
+      // Empty patterns list should not match
+      expect(matchesPathPattern('/any/path', []), isFalse);
+
+      // Empty path
+      expect(matchesPathPattern('', ['']), isTrue);
+      expect(matchesPathPattern('', ['*']), isFalse); // * requires at least one non-slash char
+      expect(matchesPathPattern('', ['**']), isTrue);
+
+      // Root path
+      expect(matchesPathPattern('/', ['/']), isTrue);
+      expect(matchesPathPattern('/', ['/*']), isFalse);
+    });
+
+    test('complex patterns', () {
+      // Mixed wildcards
+      expect(matchesPathPattern('/api/v1/users/123/posts/456/comments', ['/api/*/users/*/posts/**']), isTrue);
+      expect(matchesPathPattern('/users/123/profile/settings/advanced', ['/users/*/profile/**']), isTrue);
+
+      // Wildcard at start (matches one segment)
+      expect(matchesPathPattern('/dynamic/endpoint', ['*/endpoint']), isTrue);
+      expect(matchesPathPattern('/some/deep/path/endpoint', ['**/endpoint']), isTrue);
+    });
+
+    test('no match cases', () {
+      // Different structure
+      expect(matchesPathPattern('/users/123/update', ['/posts/*/create']), isFalse);
+      expect(matchesPathPattern('/api/v1/users', ['/api/v2/*']), isFalse);
+
+      // Too many segments for single *
+      expect(matchesPathPattern('/api/deep/nested/path', ['/api/*']), isFalse);
+      expect(matchesPathPattern('/users/123/profile/update', ['/users/*/update']), isFalse);
+
+      // Insufficient segments for **
+      expect(matchesPathPattern('/api', ['/api/**/endpoint']), isFalse);
+    });
+  });
+}