/swift-openapi-client-workflow

name: swift-openapi-client-workflow
description: Build, integrate, test, and diagnose Swift OpenAPI Generator clients in Apple-platform apps and Swift packages using OpenAPIURLSession, OpenAPIRuntime, URLSessionTransport, SwiftPM plugins, Apple docs, Dash docsets, and clear handoffs to server-side Swift OpenAPI workflows when the API contract or server transport changes.
license: Apache-2.0
metadata:
  owner: gaelic-ghost
  repo: apple-dev-skills
  category: apple-swift-openapi-client
allowed-tools: Read Bash(rg:*) Bash(git:*) Bash(swift:*) Bash(find:*) Bash(sqlite3:*) Bash(curl:*)

Swift OpenAPI Client Workflow

Purpose

Add or diagnose generated Swift OpenAPI clients in Apple-platform code without confusing app-side networking with server-side transport work.

The practical decision is where the OpenAPI document lives, which app or package target runs Swift OpenAPI Generator, how the generated `Client` is configured with `OpenAPIURLSession`, how calls are isolated from UI state, and which tests prove request, response, auth, cancellation, and error behavior.

When To Use

• Use this skill when an iOS, macOS, watchOS, tvOS, visionOS, or Swift package client should call an HTTP API from an OpenAPI description.
• Use this skill when adding or changing `swift-openapi-generator`, `swift-openapi-runtime`, or `swift-openapi-urlsession` dependencies for client generation.
• Use this skill when wiring `openapi.yaml`, `openapi.json`, or `openapi-generator-config.yaml` into an app-supporting package or target.
• Use this skill when diagnosing generated client symbols such as `Client`, `APIProtocol`, `Operations`, `Components`, response enums, content-type cases, undocumented responses, or transport errors.
• Use this skill when integrating generated calls into SwiftUI, AppKit, UIKit, Observation, async tasks, app services, or test doubles.
• Do not use this skill for generated server handlers, Vapor transport, Hummingbird transport, JSON-RPC, gRPC, or MCP-style service contracts. Hand that to `server-side-swift:openapi-rpc-workflow` when available.
• Do not use this skill for ordinary `URLSession` networking with no OpenAPI contract.

Source Check

Start with the Apple and Swift docs gate:

• Use `explore-apple-swift-docs` for Apple framework behavior, `URLSession`, Foundation networking, Xcode package integration, Swift concurrency, Observation, SwiftUI, UIKit, AppKit, or platform lifecycle behavior.
• Use local Dash or official docs before claiming current Apple or Swift API behavior.
• Look in Dash Swift docsets for `appleswiftopenapigenerator`, `appleswiftopenapiruntime`, `appleswiftopenapiurlsession`, `swiftlangswiftpackagemanager`, and Apple Foundation or platform docs when available.
• Use [Introducing Swift OpenAPI Generator](https://www.swift.org/blog/introducing-swift-openapi-generator/) for the official client/server overview, generated `Client`, `APIProtocol`, `ClientTransport`, and `URLSessionTransport` shape.
• Use [apple/swift-openapi-generator](https://github.com/apple/swift-openapi-generator) for current generator behavior, plugin setup, examples, and supported OpenAPI features.
• Use [apple/swift-openapi-runtime](https://github.com/apple/swift-openapi-runtime) for generated runtime types, middleware concepts, and shared abstractions.
• Use [apple/swift-openapi-urlsession](https://github.com/apple/swift-openapi-urlsession) for the `OpenAPIURLSession` transport and platform support.
• Use [Swift Package Manager documentation](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/) for package plugin, target, dependency, and build behavior.

Do not claim current generator, URLSession transport, package-plugin, or Apple framework behavior from memory when current docs can be checked.

Planning Workflow

1. Inspect project shape:

• `Package.swift`
• `.xcodeproj`, `.xcworkspace`, package dependencies, and target membership when present
• OpenAPI document path
• `openapi-generator-config.yaml`
• app target, shared client package target, generated-code target, and test targets
• networking service or API client owner
• SwiftUI, Observation, AppKit, UIKit, or other UI entry points that call the client

2. Identify the client ownership shape:

• app target owns generated client directly
• shared Swift package owns generated client for one or more apps
• generated client wraps a server-side Swift service in the same workspace
• existing hand-written client is being replaced or wrapped

3. Confirm the generator stack:

• Swift OpenAPI Generator package plugin
• OpenAPIRuntime runtime dependency
• OpenAPIURLSession transport for Apple-platform URL loading
• client generation in `openapi-generator-config.yaml`

4. Keep generated transport code away from UI views. Views should call a small app-facing service, model, environment value, or dependency shape that can be tested. 5. Keep the OpenAPI document and generator config reviewable, because they define the generated Swift symbols and response cases. 6. Validate through build, focused client tests, and app or package tests before recommending runtime manual checks.

Client Integration

When adding Swift OpenAPI client generation:

• add fetchable package dependencies for `swift-openapi-generator`, `swift-openapi-runtime`, and `swift-openapi-urlsession`
• add the `OpenAPIGenerator` plugin to the target that owns the OpenAPI document
• add `OpenAPIRuntime` and `OpenAPIURLSession` products to the generated-client target
• configure `openapi-generator-config.yaml` to generate `types` and `client`
• instantiate generated `Client` with a documented server URL and `URLSessionTransport`
• keep base URL, auth tokens, and environment selection outside generated types
• keep secrets out of source control

For Xcode app projects, preserve project ownership. If package dependency or target membership changes require Xcode-aware mutation, hand off to `xcode-build-run-workflow` rathe