Command Plugin for generating the source code

Package.swift

@@ -27,6 +27,7 @@ let package = Package(
     products: [
         .executable(name: "swift-openapi-generator", targets: ["swift-openapi-generator"]),
         .plugin(name: "OpenAPIGenerator", targets: ["OpenAPIGenerator"]),
+        .plugin(name: "OpenAPIGeneratorCommandPlugin", targets: ["OpenAPIGeneratorCommandPlugin"]),
         .library(name: "_OpenAPIGeneratorCore", targets: ["_OpenAPIGeneratorCore"]),
     ],
     dependencies: [
@@ -134,5 +135,19 @@ let package = Package(
                 "swift-openapi-generator",
             ]
         ),
+
+        .plugin(
+            name: "OpenAPIGeneratorCommandPlugin",
+            capability: Target.PluginCapability.command(
+                intent: .custom(
+                    verb: "generate-openapi-code",
+                    description: "Generates OpenAPI code"
+                ),
+                permissions: [.writeToPackageDirectory(reason: "To generate OpenAPI code")]
+            ),
+            dependencies: [
+                "swift-openapi-generator",
+            ]
+        )
     ]
 )

Plugins/OpenAPIGenerator/PluginsShared

@@ -0,0 +1 @@
+../../Plugins/PluginsShared

Plugins/OpenAPIGenerator/plugin.swift

@@ -16,81 +16,30 @@ import Foundation
 
 @main
 struct SwiftOpenAPIGeneratorPlugin {
-    enum Error: Swift.Error, CustomStringConvertible, LocalizedError {
-        case incompatibleTarget(targetName: String)
-        case noConfigFound(targetName: String)
-        case noDocumentFound(targetName: String)
-        case multiConfigFound(targetName: String, files: [Path])
-        case multiDocumentFound(targetName: String, files: [Path])
-
-        var description: String {
-            switch self {
-            case .incompatibleTarget(let targetName):
-                return
-                    "Incompatible target called '\(targetName)'. Only Swift source targets can be used with the Swift OpenAPI generator plugin."
-            case .noConfigFound(let targetName):
-                return
-                    "No config file found in the target named '\(targetName)'. Add a file called 'openapi-generator-config.yaml' or 'openapi-generator-config.yml' to the target's source directory. See documentation for details."
-            case .noDocumentFound(let targetName):
-                return
-                    "No OpenAPI document found in the target named '\(targetName)'. Add a file called 'openapi.yaml', 'openapi.yml' or 'openapi.json' (can also be a symlink) to the target's source directory. See documentation for details."
-            case .multiConfigFound(let targetName, let files):
-                return
-                    "Multiple config files found in the target named '\(targetName)', but exactly one is required. Found \(files.map(\.description).joined(separator: " "))."
-            case .multiDocumentFound(let targetName, let files):
-                return
-                    "Multiple OpenAPI documents found in the target named '\(targetName)', but exactly one is required. Found \(files.map(\.description).joined(separator: " "))."
-            }
-        }
-
-        var errorDescription: String? {
-            description
-        }
-    }
-
-    private var supportedConfigFiles: Set<String> { Set(["yaml", "yml"].map { "openapi-generator-config." + $0 }) }
-    private var supportedDocFiles: Set<String> { Set(["yaml", "yml", "json"].map { "openapi." + $0 }) }
-
     func createBuildCommands(
-        pluginWorkDirectory: PackagePlugin.Path,
-        tool: (String) throws -> PackagePlugin.PluginContext.Tool,
+        pluginWorkDirectory: Path,
+        tool: (String) throws -> PluginContext.Tool,
         sourceFiles: FileList,
         targetName: String
     ) throws -> [Command] {
-        let inputFiles = sourceFiles
-        let matchedConfigs = inputFiles.filter { supportedConfigFiles.contains($0.path.lastComponent) }.map(\.path)
-        guard matchedConfigs.count > 0 else {
-            throw Error.noConfigFound(targetName: targetName)
-        }
-        guard matchedConfigs.count == 1 else {
-            throw Error.multiConfigFound(targetName: targetName, files: matchedConfigs)
-        }
-        let config = matchedConfigs[0]
+        let inputs = try PluginUtils.validateInputs(
+            workingDirectory: pluginWorkDirectory,
+            tool: tool,
+            sourceFiles: sourceFiles,
+            targetName: targetName,
+            invocationSource: .BuildToolPlugin
+        )
 
-        let matchedDocs = inputFiles.filter { supportedDocFiles.contains($0.path.lastComponent) }.map(\.path)
-        guard matchedDocs.count > 0 else {
-            throw Error.noDocumentFound(targetName: targetName)
-        }
-        guard matchedDocs.count == 1 else {
-            throw Error.multiDocumentFound(targetName: targetName, files: matchedDocs)
-        }
-        let doc = matchedDocs[0]
-        let genSourcesDir = pluginWorkDirectory.appending("GeneratedSources")
-        let outputFiles: [Path] = GeneratorMode.allCases.map { genSourcesDir.appending($0.outputFileName) }
+        let outputFiles: [Path] = GeneratorMode.allCases.map { inputs.genSourcesDir.appending($0.outputFileName) }
         return [
             .buildCommand(
                 displayName: "Running swift-openapi-generator",
-                executable: try tool("swift-openapi-generator").path,
-                arguments: [
-                    "generate", "\(doc)",
-                    "--config", "\(config)",
-                    "--output-directory", "\(genSourcesDir)",
-                    "--is-plugin-invocation",
-                ],
+                executable: inputs.tool.path,
+                arguments: inputs.arguments,
                 environment: [:],
                 inputFiles: [
-                    config,
-                    doc,
+                    inputs.config,
+                    inputs.doc,
                 ],
                 outputFiles: outputFiles
             )
@@ -104,7 +53,7 @@ extension SwiftOpenAPIGeneratorPlugin: BuildToolPlugin {
         target: Target
     ) async throws -> [Command] {
         guard let swiftTarget = target as? SwiftSourceModuleTarget else {
-            throw Error.incompatibleTarget(targetName: target.name)
+            throw PluginError.incompatibleTarget(targetName: target.name)
         }
         return try createBuildCommands(
             pluginWorkDirectory: context.pluginWorkDirectory,

Plugins/OpenAPIGeneratorCommandPlugin/PluginsShared

@@ -0,0 +1 @@
+../../Plugins/PluginsShared

Plugins/OpenAPIGeneratorCommandPlugin/plugin.swift

@@ -0,0 +1,97 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftOpenAPIGenerator open source project
+//
+// Copyright (c) 2023 Apple Inc. and the SwiftOpenAPIGenerator project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftOpenAPIGenerator project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+import PackagePlugin
+import Foundation
+
+@main
+struct SwiftOpenAPIGeneratorPlugin {
+    func runCommand(
+        targetWorkingDirectory: Path,
+        tool: (String) throws -> PluginContext.Tool,
+        sourceFiles: FileList,
+        targetName: String
+    ) throws {
+        let inputs = try PluginUtils.validateInputs(
+            workingDirectory: targetWorkingDirectory,
+            tool: tool,
+            sourceFiles: sourceFiles,
+            targetName: targetName,
+            invocationSource: .CommandPlugin
+        )
+
+        let toolUrl = URL(fileURLWithPath: inputs.tool.path.string)
+        let process = Process()
+        process.executableURL = toolUrl
+        process.arguments = inputs.arguments
+        try process.run()
+    }
+}
+
+extension SwiftOpenAPIGeneratorPlugin: CommandPlugin {
+    func performCommand(
+        context: PluginContext,
+        arguments: [String]
+    ) async throws {
+        guard arguments.count == 2, arguments[0] == "--target" else {
+            throw PluginError.badArguments(arguments: arguments)
+        }
+        let targetName = arguments[1]
+        let matchingTargets = try context.package.targets(named: [targetName])
+        // `matchingTargets.count` can't be 0 because
+        // `targets(named:)` would throw an error for that.
+        guard matchingTargets.count == 1 else {
+            throw PluginError.tooManyTargetsMatchingTargetName(targetNames: matchingTargets.map(\.name))
+        }
+        let target = matchingTargets[0]
+        guard let swiftTarget = target as? SwiftSourceModuleTarget else {
+            throw PluginError.incompatibleTarget(targetName: target.name)
+        }
+        return try runCommand(
+            targetWorkingDirectory: target.directory,
+            tool: context.tool,
+            sourceFiles: swiftTarget.sourceFiles,
+            targetName: target.name
+        )
+    }
+}
+
+#if canImport(XcodeProjectPlugin)
+import XcodeProjectPlugin
+
+extension SwiftOpenAPIGeneratorPlugin: XcodeCommandPlugin {
+    func performCommand(
+        context: XcodePluginContext,
+        arguments: [String]
+    ) throws {
+        guard arguments.count == 2, arguments[0] == "--target" else {
+            throw PluginError.badArguments(arguments: arguments)
+        }
+        let targetName = arguments[1]
+        guard let xcodeTarget = context.xcodeProject.targets.first(
+            where: { $0.displayName == targetName }
+        ) else {
+            throw PluginError.noTargetsMatchingTargetName(targetName: targetName)
+        }
+        guard let target = xcodeTarget as? SourceModuleTarget else {
+            throw PluginError.incompatibleTarget(targetName: targetName)
+        }
+        return try runCommand(
+            targetWorkingDirectory: target.directory,
+            tool: context.tool,
+            sourceFiles: xcodeTarget.inputFiles,
+            targetName: xcodeTarget.displayName
+        )
+    }
+}
+#endif

Plugins/PluginsShared/InvocationSource.swift

@@ -0,0 +1 @@
+../../Sources/swift-openapi-generator/InvocationSource.swift

Plugins/PluginsShared/PluginError.swift

@@ -0,0 +1,45 @@
+import PackagePlugin
+import Foundation
+
+enum PluginError: Swift.Error, CustomStringConvertible, LocalizedError {
+    case incompatibleTarget(targetName: String)
+    case badArguments(arguments: [String])
+    // The description is only suitable for Xcode, as it's only thrown in Xcode plugins.
+    case noTargetsMatchingTargetName(targetName: String)
+    // The description is not suitable for Xcode, as it's not thrown in Xcode plugins.
+    case tooManyTargetsMatchingTargetName(targetNames: [String])
+    case noConfigFound(targetName: String)
+    case noDocumentFound(targetName: String)
+    case multiConfigFound(targetName: String, files: [Path])
+    case multiDocumentFound(targetName: String, files: [Path])
+
+    var description: String {
+        switch self {
+        case .incompatibleTarget(let targetName):
+            return
+            "Incompatible target called '\(targetName)'. Only Swift source targets can be used with the Swift OpenAPI generator plugin."
+        case .badArguments(let arguments):
+            return "Bad arguments provided: \(arguments). On Xcode, use Xcode's run plugin UI to choose a specific target. On CLI, pass a specific target's name to the command like so: '--target TARGET_NAME'"
+        case .noTargetsMatchingTargetName(let targetName):
+            return "No target called '\(targetName)' were found. Use Xcode's UI to choose a single specific target before triggering the command plugin."
+        case .tooManyTargetsMatchingTargetName(let targetNames):
+            return "Too many targets found matching the provided target name: '\(targetNames)'. Target name must be specific enough for the plugin to only find a single target."
+        case .noConfigFound(let targetName):
+            return
+            "No config file found in the target named '\(targetName)'. Add a file called 'openapi-generator-config.yaml' or 'openapi-generator-config.yml' to the target's source directory. See documentation for details."
+        case .noDocumentFound(let targetName):
+            return
+            "No OpenAPI document found in the target named '\(targetName)'. Add a file called 'openapi.yaml', 'openapi.yml' or 'openapi.json' (can also be a symlink) to the target's source directory. See documentation for details."
+        case .multiConfigFound(let targetName, let files):
+            return
+            "Multiple config files found in the target named '\(targetName)', but exactly one is required. Found \(files.map(\.description).joined(separator: " "))."
+        case .multiDocumentFound(let targetName, let files):
+            return
+            "Multiple OpenAPI documents found in the target named '\(targetName)', but exactly one is required. Found \(files.map(\.description).joined(separator: " "))."
+        }
+    }
+
+    var errorDescription: String? {
+        description
+    }
+}

Plugins/PluginsShared/PluginUtils.swift

@@ -0,0 +1,59 @@
+import PackagePlugin
+
+enum PluginUtils {
+    private static var supportedConfigFiles: Set<String> { Set(["yaml", "yml"].map { "openapi-generator-config." + $0 }) }
+    private static var supportedDocFiles: Set<String> { Set(["yaml", "yml", "json"].map { "openapi." + $0 }) }
+
+    struct ValidatedInputs {
+        let doc: Path
+        let config: Path
+        let genSourcesDir: Path
+        let arguments: [String]
+        let tool: PluginContext.Tool
+    }
+
+    static func validateInputs(
+        workingDirectory: Path,
+        tool: (String) throws -> PluginContext.Tool,
+        sourceFiles: FileList,
+        targetName: String,
+        invocationSource: InvocationSource
+    ) throws -> ValidatedInputs {
+        let inputFiles = sourceFiles
+        let matchedConfigs = inputFiles.filter { supportedConfigFiles.contains($0.path.lastComponent) }.map(\.path)
+        guard matchedConfigs.count > 0 else {
+            throw PluginError.noConfigFound(targetName: targetName)
+        }
+        guard matchedConfigs.count == 1 else {
+            throw PluginError.multiConfigFound(targetName: targetName, files: matchedConfigs)
+        }
+        let config = matchedConfigs[0]
+
+        let matchedDocs = inputFiles.filter { supportedDocFiles.contains($0.path.lastComponent) }.map(\.path)
+        guard matchedDocs.count > 0 else {
+            throw PluginError.noDocumentFound(targetName: targetName)
+        }
+        guard matchedDocs.count == 1 else {
+            throw PluginError.multiDocumentFound(targetName: targetName, files: matchedDocs)
+        }
+        let doc = matchedDocs[0]
+        let genSourcesDir = workingDirectory.appending("GeneratedSources")
+
+        let arguments = [
+            "generate", "\(doc)",
+            "--config", "\(config)",
+            "--output-directory", "\(genSourcesDir)",
+            "--invoked-from", "\(invocationSource.rawValue)"
+        ]
+
+        let tool = try tool("swift-openapi-generator")
+
+        return ValidatedInputs(
+            doc: doc,
+            config: config,
+            genSourcesDir: genSourcesDir,
+            arguments: arguments,
+            tool: tool
+        )
+    }
+}

Sources/_OpenAPIGeneratorCore/Layers/StructuredSwiftRepresentation.swift

@@ -377,6 +377,11 @@ struct ParameterDescription: Equatable, Codable {
     /// For example, in `bar baz: String = "hi"`, `name` is `baz`.
     var name: String? = nil
 
+    /// The existential any keyword.
+    ///
+    /// For example, in `bar baz: any Client = ...`, `any` is the keyword referred to here.
+    var anyKeyword: Bool = false
+
     /// The type name of the parameter.
     ///
     /// For example, in `bar baz: String = "hi"`, `type` is `String`.

Sources/_OpenAPIGeneratorCore/Renderer/TextBasedRenderer.swift

@@ -610,6 +610,9 @@ struct TextBasedRenderer: RendererProtocol {
             }
         }
         words.append(":")
+        if parameterDescription.anyKeyword {
+            words.append("any")
+        }
         words.append(parameterDescription.type)
         if let defaultValue = parameterDescription.defaultValue {
             words.append("=")

Sources/_OpenAPIGeneratorCore/Translator/ClientTranslator/ClientTranslator.swift

@@ -79,10 +79,14 @@ struct ClientFileTranslator: FileTranslator {
                         type: Constants.Configuration.typeName,
                         defaultValue: .dot("init").call([])
                     ),
-                    .init(label: "transport", type: Constants.Client.Transport.typeName),
+                    .init(
+                        label: "transport",
+                        anyKeyword: true,
+                        type: Constants.Client.Transport.typeName
+                    ),
                     .init(
                         label: "middlewares",
-                        type: "[\(Constants.Client.Middleware.typeName)]",
+                        type: "[any \(Constants.Client.Middleware.typeName)]",
                         defaultValue: .literal(.array([]))
                     ),
                 ],