Merge branch 'main' into type-substitutions

czechboy0 · web-flow · commit d4f810312210 · 2025-06-17T13:07:38.000+02:00
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -11,7 +11,6 @@ jobs:
     name: Unit tests
     uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
     with:
-      linux_5_9_arguments_override: "--explicit-target-dependency-import-check error"
       linux_5_10_arguments_override: "--explicit-target-dependency-import-check error"
       linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error"
       linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error"
diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml
@@ -17,7 +17,6 @@ jobs:
     name: Unit tests
     uses: apple/swift-nio/.github/workflows/unit_tests.yml@main
     with:
-      linux_5_9_arguments_override: "--explicit-target-dependency-import-check error"
       linux_5_10_arguments_override: "--explicit-target-dependency-import-check error"
       linux_6_0_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error"
       linux_6_1_arguments_override: "-Xswiftc -warnings-as-errors --explicit-target-dependency-import-check error"
diff --git a/Examples/auth-client-middleware-example/Package.swift b/Examples/auth-client-middleware-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/auth-server-middleware-example/Package.swift b/Examples/auth-server-middleware-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/bidirectional-event-streams-client-example/Package.swift b/Examples/bidirectional-event-streams-client-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/bidirectional-event-streams-server-example/Package.swift b/Examples/bidirectional-event-streams-server-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/command-line-client-example/Package.swift b/Examples/command-line-client-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/curated-client-library-example/Package.swift b/Examples/curated-client-library-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/event-streams-client-example/Package.swift b/Examples/event-streams-client-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/event-streams-server-example/Package.swift b/Examples/event-streams-server-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/hello-world-async-http-client-example/Package.swift b/Examples/hello-world-async-http-client-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/hello-world-hummingbird-server-example/Package.swift b/Examples/hello-world-hummingbird-server-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9.2
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/hello-world-urlsession-client-example/Package.swift b/Examples/hello-world-urlsession-client-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/hello-world-vapor-server-example/Package.swift b/Examples/hello-world-vapor-server-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9.2
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/logging-middleware-oslog-example/Package.swift b/Examples/logging-middleware-oslog-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/logging-middleware-swift-log-example/Package.swift b/Examples/logging-middleware-swift-log-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/manual-generation-generator-cli-example/Package.swift b/Examples/manual-generation-generator-cli-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/manual-generation-package-plugin-example/Package.swift b/Examples/manual-generation-package-plugin-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/metrics-middleware-example/Package.swift b/Examples/metrics-middleware-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/postgres-database-example/Package.swift b/Examples/postgres-database-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/retrying-middleware-example/Package.swift b/Examples/retrying-middleware-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/shared-types-client-server-example/Package.swift b/Examples/shared-types-client-server-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/streaming-chatgpt-proxy/Package.swift b/Examples/streaming-chatgpt-proxy/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version: 5.9
+// swift-tools-version:5.10
 import PackageDescription
 
 let package = Package(
diff --git a/Examples/swagger-ui-endpoint-example/Package.swift b/Examples/swagger-ui-endpoint-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/tracing-middleware-example/Package.swift b/Examples/tracing-middleware-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/various-content-types-client-example/Package.swift b/Examples/various-content-types-client-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Examples/various-content-types-server-example/Package.swift b/Examples/various-content-types-server-example/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9.2
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/IntegrationTest/Package.swift b/IntegrationTest/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
diff --git a/Package.swift b/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:5.9
+// swift-tools-version:5.10
 //===----------------------------------------------------------------------===//
 //
 // This source file is part of the SwiftOpenAPIGenerator open source project
@@ -46,7 +46,7 @@ let package = Package(
 
         // Read OpenAPI documents
         .package(url: "https://github.com/mattpolzin/OpenAPIKit", from: "3.3.0"),
-        .package(url: "https://github.com/jpsim/Yams", "4.0.0"..<"6.0.0"),
+        .package(url: "https://github.com/jpsim/Yams", "4.0.0"..<"7.0.0"),
 
         // CLI Tool
         .package(url: "https://github.com/apple/swift-argument-parser", from: "1.3.0"),
diff --git a/Sources/_OpenAPIGeneratorCore/Config.swift b/Sources/_OpenAPIGeneratorCore/Config.swift
@@ -46,6 +46,9 @@ public struct Config: Sendable {
     /// Additional imports to add to each generated file.
     public var additionalImports: [String]
 
+    /// Additional comments to add to the top of each generated file.
+    public var additionalFileComments: [String]
+
     /// Filter to apply to the OpenAPI document before generation.
     public var filter: DocumentFilter?
 
@@ -71,6 +74,7 @@ public struct Config: Sendable {
     ///   - mode: The mode to use for generation.
     ///   - access: The access modifier to use for generated declarations.
     ///   - additionalImports: Additional imports to add to each generated file.
+    ///   - additionalFileComments: Additional comments to add to the top of each generated file.
     ///   - filter: Filter to apply to the OpenAPI document before generation.
     ///   - namingStrategy: The naming strategy to use for deriving Swift identifiers from OpenAPI identifiers.
     ///     Defaults to `defensive`.
@@ -82,6 +86,7 @@ public struct Config: Sendable {
         mode: GeneratorMode,
         access: AccessModifier,
         additionalImports: [String] = [],
+        additionalFileComments: [String] = [],
         filter: DocumentFilter? = nil,
         namingStrategy: NamingStrategy,
         nameOverrides: [String: String] = [:],
@@ -91,6 +96,7 @@ public struct Config: Sendable {
         self.mode = mode
         self.access = access
         self.additionalImports = additionalImports
+        self.additionalFileComments = additionalFileComments
         self.filter = filter
         self.namingStrategy = namingStrategy
         self.nameOverrides = nameOverrides
diff --git a/Sources/_OpenAPIGeneratorCore/Translator/ClientTranslator/ClientTranslator.swift b/Sources/_OpenAPIGeneratorCore/Translator/ClientTranslator/ClientTranslator.swift
@@ -32,7 +32,7 @@ struct ClientFileTranslator: FileTranslator {
 
         let doc = parsedOpenAPI
 
-        let topComment: Comment = .inline(Constants.File.topComment)
+        let topComment = self.topComment
 
         let imports =
             Constants.File.clientServerImports + config.additionalImports.map { ImportDescription(moduleName: $0) }
diff --git a/Sources/_OpenAPIGeneratorCore/Translator/FileTranslator.swift b/Sources/_OpenAPIGeneratorCore/Translator/FileTranslator.swift
@@ -83,6 +83,12 @@ extension FileTranslator {
         )
         return TranslatorContext(safeNameGenerator: overridingGenerator)
     }
+
+    /// Creates a top comment that includes the default "do not modify" comment
+    /// and any additional file comments from the configuration.
+    var topComment: Comment {
+        .inline(([Constants.File.topComment] + config.additionalFileComments).joined(separator: "\n"))
+    }
 }
 
 /// A set of configuration values for concrete file translators.
diff --git a/Sources/_OpenAPIGeneratorCore/Translator/ServerTranslator/ServerTranslator.swift b/Sources/_OpenAPIGeneratorCore/Translator/ServerTranslator/ServerTranslator.swift
@@ -30,7 +30,7 @@ struct ServerFileTranslator: FileTranslator {
 
         let doc = parsedOpenAPI
 
-        let topComment: Comment = .inline(Constants.File.topComment)
+        let topComment = self.topComment
 
         let imports =
             Constants.File.clientServerImports + config.additionalImports.map { ImportDescription(moduleName: $0) }
diff --git a/Sources/_OpenAPIGeneratorCore/Translator/TypesTranslator/TypesFileTranslator.swift b/Sources/_OpenAPIGeneratorCore/Translator/TypesTranslator/TypesFileTranslator.swift
@@ -32,7 +32,7 @@ struct TypesFileTranslator: FileTranslator {
 
         let doc = parsedOpenAPI
 
-        let topComment: Comment = .inline(Constants.File.topComment)
+        let topComment = self.topComment
 
         let imports = Constants.File.imports + config.additionalImports.map { ImportDescription(moduleName: $0) }
 
diff --git a/Sources/swift-openapi-generator/Documentation.docc/Articles/Configuring-the-generator.md b/Sources/swift-openapi-generator/Documentation.docc/Articles/Configuring-the-generator.md
@@ -35,6 +35,7 @@ The configuration file has the following keys:
     - `package`: Generated API is accessible from other modules within the same package or project.
     - `internal` (default): Generated API is accessible from the containing module only.
 - `additionalImports` (optional): array of strings. Each string value is a Swift module name. An import statement will be added to the generated source files for each module.
+- `additionalFileComments` (optional): array of strings. Each string value is a comment that will be added to the top of each generated file (after the do-not-edit comment). Useful for adding directives like `swift-format-ignore-file` or `swiftlint:disable all`.
 - `filter` (optional): Filters to apply to the OpenAPI document before generation.
     - `operations`: Operations with these operation IDs will be included in the filter.
     - `tags`: Operations tagged with these tags will be included in the filter.
@@ -95,6 +96,18 @@ additionalImports:
 accessModifier: public
 ```
 
+To add file comments to exclude generated files from formatting tools:
+
+```yaml
+generate:
+  - types
+  - client
+namingStrategy: idiomatic
+additionalFileComments:
+  - "swift-format-ignore-file"
+  - "swiftlint:disable all"
+```
+
 ### Document filtering
 
 The generator supports filtering the OpenAPI document prior to generation, which can be useful when
diff --git a/Sources/swift-openapi-generator/GenerateOptions+runGenerator.swift b/Sources/swift-openapi-generator/GenerateOptions+runGenerator.swift
@@ -32,6 +32,7 @@ extension _GenerateOptions {
         let sortedModes = try resolvedModes(config)
         let resolvedAccessModifier = resolvedAccessModifier(config)
         let resolvedAdditionalImports = resolvedAdditionalImports(config)
+        let resolvedAdditionalFileComments = resolvedAdditionalFileComments(config)
         let resolvedNamingStragy = resolvedNamingStrategy(config)
         let resolvedNameOverrides = resolvedNameOverrides(config)
         let resolvedTypeOverrides = resolvedTypeOverrides(config)
@@ -41,6 +42,7 @@ extension _GenerateOptions {
                 mode: $0,
                 access: resolvedAccessModifier,
                 additionalImports: resolvedAdditionalImports,
+                additionalFileComments: resolvedAdditionalFileComments,
                 filter: config?.filter,
                 namingStrategy: resolvedNamingStragy,
                 nameOverrides: resolvedNameOverrides,
@@ -72,6 +74,7 @@ extension _GenerateOptions {
             - Plugin source: \(pluginSource?.rawValue ?? "<none>")
             - Is dry run: \(isDryRun)
             - Additional imports: \(resolvedAdditionalImports.isEmpty ? "<none>" : resolvedAdditionalImports.joined(separator: ", "))
+            - Additional file comments: \(resolvedAdditionalFileComments.isEmpty ? "<none>" : resolvedAdditionalFileComments.joined(separator: ", "))
             """
         )
         do {
diff --git a/Sources/swift-openapi-generator/GenerateOptions.swift b/Sources/swift-openapi-generator/GenerateOptions.swift
@@ -40,6 +40,8 @@ struct _GenerateOptions: ParsableArguments {
 
     @Option(help: "Additional import to add to all generated files.") var additionalImport: [String] = []
 
+    @Option(help: "Additional file comment to add to all generated files.") var additionalFileComment: [String] = []
+
     @Option(help: "Pre-release feature to enable. Options: \(FeatureFlag.prettyListing).") var featureFlag:
         [FeatureFlag] = []
 
@@ -81,6 +83,17 @@ extension _GenerateOptions {
         return []
     }
 
+    /// Returns a list of additional file comments requested by the user.
+    /// - Parameter config: The configuration specified by the user.
+    /// - Returns: A list of additional file comments requested by the user.
+    func resolvedAdditionalFileComments(_ config: _UserConfig?) -> [String] {
+        if !additionalFileComment.isEmpty { return additionalFileComment }
+        if let additionalFileComments = config?.additionalFileComments, !additionalFileComments.isEmpty {
+            return additionalFileComments
+        }
+        return []
+    }
+
     /// Returns the naming strategy requested by the user.
     /// - Parameter config: The configuration specified by the user.
     /// - Returns: The naming strategy requestd by the user.
diff --git a/Sources/swift-openapi-generator/UserConfig.swift b/Sources/swift-openapi-generator/UserConfig.swift
@@ -30,6 +30,10 @@ struct _UserConfig: Codable {
     /// generated Swift file.
     var additionalImports: [String]?
 
+    /// A list of additional comments that are added to the top of every
+    /// generated Swift file.
+    var additionalFileComments: [String]?
+
     /// Filter to apply to the OpenAPI document before generation.
     var filter: DocumentFilter?
 
@@ -54,6 +58,7 @@ struct _UserConfig: Codable {
         case generate
         case accessModifier
         case additionalImports
+        case additionalFileComments
         case filter
         case namingStrategy
         case nameOverrides
diff --git a/Tests/OpenAPIGeneratorCoreTests/Test_Config.swift b/Tests/OpenAPIGeneratorCoreTests/Test_Config.swift
@@ -17,4 +17,17 @@ import OpenAPIKit
 
 final class Test_Config: Test_Core {
     func testDefaultAccessModifier() { XCTAssertEqual(Config.defaultAccessModifier, .internal) }
+    func testAdditionalFileComments() {
+        let config = Config(
+            mode: .types,
+            access: .public,
+            additionalFileComments: ["swift-format-ignore-file", "swiftlint:disable all"],
+            namingStrategy: .defensive
+        )
+        XCTAssertEqual(config.additionalFileComments, ["swift-format-ignore-file", "swiftlint:disable all"])
+    }
+    func testEmptyAdditionalFileComments() {
+        let config = Config(mode: .types, access: .public, namingStrategy: .defensive)
+        XCTAssertEqual(config.additionalFileComments, [])
+    }
 }
diff --git a/Tests/OpenAPIGeneratorReferenceTests/SnippetBasedReferenceTests.swift b/Tests/OpenAPIGeneratorReferenceTests/SnippetBasedReferenceTests.swift

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// swift-tools-version:5.9`
	`1`	`+// swift-tools-version:5.10`
`2`	`2`	`//===----------------------------------------------------------------------===//`
`3`	`3`	`//`
`4`	`4`	`// This source file is part of the SwiftOpenAPIGenerator open source project`