swift-openapi-client-workflow

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 for the official client/server overview, generated Client, APIProtocol, ClientTransport, and URLSessionTransport shape.
• Use apple/swift-openapi-generator for current generator behavior, plugin setup, examples, and supported OpenAPI features.
• Use apple/swift-openapi-runtime for generated runtime types, middleware concepts, and shared abstractions.
• Use apple/swift-openapi-urlsession for the OpenAPIURLSession transport and platform support.
• Use Swift Package Manager documentation 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 rather than editing .pbxproj casually.

For Swift package clients, keep Package.swift readable and intentional. Prefer SwiftPM commands or focused manifest edits that match the existing package style.

App-Side Behavior

When connecting generated clients to app code:

• isolate generated response enums from UI views with a small app-facing API when the UI would otherwise switch over transport details everywhere
• handle documented response cases explicitly
• handle .undocumented responses with a readable error path
• preserve task cancellation; do not hide CancellationError behind generic networking failures
• keep authentication, retry, logging, and metrics in a transport or app-service boundary instead of scattering them across views
• map generated schemas into local app models only when the app needs persistence, editing, identity, or UI-specific state
• avoid using generated types as SwiftData, Core Data, or UI state models unless the generated schema is intentionally stable enough for that job

When an API contract change is needed, stop and surface that as server or contract work. Do not quietly patch the generated client around a mismatched server contract.

Testing And Validation

Choose the smallest useful check:

• swift build to force package-plugin generation and type checking
• swift test for package-level client wrappers, request mapping, response handling, and fake transport behavior
• Xcode build or test workflow when the app target, scheme, simulator, or package integration is the real risk
• local HTTP checks only when integration with a real server, auth header, TLS, cookie, redirect, or streaming behavior must be proven end to end

Prefer fake ClientTransport or app-service seams for tests when the behavior does not require a real network. Use real URLSessionTransport checks only when Foundation networking behavior is the thing being verified.

When validation fails, name the exact OpenAPI operation, generated symbol, target, package plugin, transport, response case, or Apple framework surface involved. Include the likely cause, such as a missing config file, wrong target plugin placement, stale operation ID, unsupported schema shape, missing OpenAPIURLSession dependency, target membership drift, or an app lifecycle call running from the wrong task boundary.

Output Shape

Return:

1. Client shape: OpenAPI document, generator config, target ownership, generated symbols, transport, and app-facing owner.
2. Docs used: Apple, Swift, Dash, GitHub, or SwiftPM docs consulted.
3. Command path: exact SwiftPM, Xcode, generator, validation, test, run, or HTTP commands run or recommended.
4. Behavior: operations, inputs, outputs, auth, cancellation, errors, UI handoff, and contract-change decisions.
5. Validation: build, test, app run, fake transport, real HTTP, or skipped checks.
6. Handoffs: server-side OpenAPI/RPC, Xcode build/run, Xcode testing, Swift package, docs exploration, persistence, or observability follow-up when the task crosses this skill's boundary.

Guardrails

• Do not turn an Apple app workflow into server-side transport work.
• Do not hide API contract mismatches behind app-side adapters without saying the server contract needs attention.
• Do not commit generated caches, secrets, local server URLs as production defaults, or machine-local dependency paths.
• Do not hand-edit Package.resolved.
• Do not edit Xcode project files casually; use Xcode-aware workflows when project membership or scheme behavior is part of the change.
• Do not let generated response enums leak into every view when a small app-facing service would keep UI code readable and testable.