# apple/swift-openapi-runtime architecture

> Architecture diagram of the GitHub repository apple/swift-openapi-runtime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apple/swift-openapi-runtime
- Repository: https://github.com/apple/swift-openapi-runtime

## Overview

Swift OpenAPI Runtime supplies shared types and pluggable client/server interfaces for code generated by Swift OpenAPI Generator. The principal client workflow serializes operation input, passes the request through middleware to a transport, then deserializes the response; the server side exposes corresponding transport and middleware abstractions for generated handlers. URI parameter coding, body conversion, multipart, and event-stream support are distinct runtime capabilities. The tree and excerpts support the client dispatch details; server wiring and some format integrations are represented at the documented/module level, with uncertain call links omitted.

Main entry points: [`Sources/OpenAPIRuntime/Conversion/Converter+Client.swift`](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Conversion/Converter%2BClient.swift) (Client conversion), [`Sources/OpenAPIRuntime/Interface/UniversalClient.swift`](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/UniversalClient.swift) (Universal client), [`Sources/OpenAPIRuntime/Interface/HTTPBody.swift`](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/HTTPBody.swift) (HTTP body), [`Sources/OpenAPIRuntime/Interface/ClientTransport.swift`](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/ClientTransport.swift) (Client middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client Runtime"]
  node_universal_client["Universal client"]
  node_client_converter["Client conversion"]
  node_client_middleware["Client middleware"]
  node_client_transport["Client transport"]
end

subgraph group_server["Server Runtime"]
  node_server_transport["Server transport"]
  node_server_middleware["Server middleware"]
  node_query_middleware["Query normalization"]
end

subgraph group_coding["HTTP Coding"]
  node_uri_encoder["URI encoder<br/>[URIEncoder.swift]"]
  node_uri_serializer["URI serializer"]
  node_uri_parser["URI parser<br/>[URIParser.swift]"]
  node_uri_decoder["URI decoder<br/>[URIDecoder.swift]"]
  node_conversion_common["Common conversion"]
end

subgraph group_formats["Body Formats"]
  node_multipart["Multipart streams"]
  node_event_streams["Event streams"]
end

subgraph group_shared["Shared Types"]
  node_http_body["HTTP body<br/>[HTTPBody.swift]"]
  node_base_types["Base value types<br/>[OpenAPIValue.swift]"]
  node_client_errors["Client errors<br/>[ClientError.swift]"]
end

node_generated_client(("Generated client"))
node_generated_server(("Generated server"))
node_http_types["HTTP types"]

node_generated_client -->|"invokes operations"| node_universal_client
node_universal_client -->|"serializes input"| node_client_converter
node_client_converter -->|"encodes parameters"| node_uri_encoder
node_uri_encoder -->|"serializes nodes"| node_uri_serializer
node_universal_client -->|"dispatches through"| node_client_middleware
node_client_middleware -->|"forwards request"| node_client_transport
node_client_transport -->|"exchanges HTTP"| node_http_types
node_universal_client -->|"deserializes response"| node_client_converter
node_client_converter -->|"decodes parameters"| node_uri_decoder
node_uri_decoder -->|"parses URI data"| node_uri_parser
node_universal_client -->|"wraps failures"| node_client_errors
node_generated_server -.->|"uses interface"| node_server_transport
node_server_transport -.->|"supports middleware"| node_server_middleware
node_server_middleware -.->|"may include"| node_query_middleware
node_query_middleware -->|"rewrites request"| node_http_types
node_client_converter -->|"uses conversions"| node_conversion_common
node_conversion_common -->|"converts bodies"| node_http_body
node_multipart -.->|"frames body data"| node_http_body
node_event_streams -.->|"streams body data"| node_http_body
node_client_converter -.->|"converts values"| node_base_types

click node_universal_client "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/UniversalClient.swift"
click node_client_converter "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Conversion/Converter%2BClient.swift"
click node_client_middleware "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/ClientTransport.swift"
click node_client_transport "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/ClientTransport.swift"
click node_server_transport "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/ServerTransport.swift"
click node_server_middleware "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/ErrorHandlingMiddleware.swift"
click node_query_middleware "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/QuerySpaceNormalizingMiddleware.swift"
click node_uri_encoder "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/URICoder/Encoding/URIEncoder.swift"
click node_uri_serializer "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/URICoder/Serialization/URISerializer.swift"
click node_uri_parser "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/URICoder/Parsing/URIParser.swift"
click node_uri_decoder "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/URICoder/Decoding/URIDecoder.swift"
click node_conversion_common "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Conversion/Converter%2BCommon.swift"
click node_multipart "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Multipart/MultipartPublicTypes.swift"
click node_event_streams "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/EventStreams/ServerSentEvents.swift"
click node_http_body "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/HTTPBody.swift"
click node_base_types "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Base/OpenAPIValue.swift"
click node_client_errors "https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Errors/ClientError.swift"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_universal_client,node_client_converter,node_client_middleware,node_client_transport,node_generated_client toneBlue
class node_server_transport,node_server_middleware,node_query_middleware toneAmber
class node_uri_encoder,node_uri_serializer,node_uri_parser,node_uri_decoder,node_conversion_common,node_generated_server toneMint
class node_multipart,node_event_streams toneRose
class node_http_body,node_base_types,node_client_errors,node_http_types toneIndigo
```

## Components

### Client Runtime

- [Universal client](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/UniversalClient.swift): `Sources/OpenAPIRuntime/Interface/UniversalClient.swift`
- [Client conversion](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Conversion/Converter%2BClient.swift): `Sources/OpenAPIRuntime/Conversion/Converter+Client.swift`
- [Client middleware](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/ClientTransport.swift): `Sources/OpenAPIRuntime/Interface/ClientTransport.swift`
- [Client transport](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/ClientTransport.swift): `Sources/OpenAPIRuntime/Interface/ClientTransport.swift`

### Server Runtime

- [Server transport](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/ServerTransport.swift): `Sources/OpenAPIRuntime/Interface/ServerTransport.swift`
- [Server middleware](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/ErrorHandlingMiddleware.swift): `Sources/OpenAPIRuntime/Interface/ErrorHandlingMiddleware.swift`
- [Query normalization](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/QuerySpaceNormalizingMiddleware.swift): `Sources/OpenAPIRuntime/Interface/QuerySpaceNormalizingMiddleware.swift`

### HTTP Coding

- [URI encoder](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/URICoder/Encoding/URIEncoder.swift): `Sources/OpenAPIRuntime/URICoder/Encoding/URIEncoder.swift`
- [URI serializer](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/URICoder/Serialization/URISerializer.swift): `Sources/OpenAPIRuntime/URICoder/Serialization/URISerializer.swift`
- [URI parser](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/URICoder/Parsing/URIParser.swift): `Sources/OpenAPIRuntime/URICoder/Parsing/URIParser.swift`
- [URI decoder](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/URICoder/Decoding/URIDecoder.swift): `Sources/OpenAPIRuntime/URICoder/Decoding/URIDecoder.swift`
- [Common conversion](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Conversion/Converter%2BCommon.swift): `Sources/OpenAPIRuntime/Conversion/Converter+Common.swift`

### Body Formats

- [Multipart streams](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Multipart/MultipartPublicTypes.swift): `Sources/OpenAPIRuntime/Multipart/MultipartPublicTypes.swift`
- [Event streams](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/EventStreams/ServerSentEvents.swift): `Sources/OpenAPIRuntime/EventStreams/ServerSentEvents.swift`

### Shared Types

- [HTTP body](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Interface/HTTPBody.swift): `Sources/OpenAPIRuntime/Interface/HTTPBody.swift`
- [Base value types](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Base/OpenAPIValue.swift): `Sources/OpenAPIRuntime/Base/OpenAPIValue.swift`
- [Client errors](https://github.com/apple/swift-openapi-runtime/blob/main/Sources/OpenAPIRuntime/Errors/ClientError.swift): `Sources/OpenAPIRuntime/Errors/ClientError.swift`

### Other components

- **Generated client**
- **Generated server**
- **HTTP types**

## Connections

- Generated client → Universal client: invokes operations
- Universal client → Client conversion: serializes input
- Client conversion → URI encoder: encodes parameters
- URI encoder → URI serializer: serializes nodes
- Universal client → Client middleware: dispatches through
- Client middleware → Client transport: forwards request
- Client transport → HTTP types: exchanges HTTP
- Universal client → Client conversion: deserializes response
- Client conversion → URI decoder: decodes parameters
- URI decoder → URI parser: parses URI data
- Universal client → Client errors: wraps failures
- Generated server → Server transport: uses interface
- Server transport → Server middleware: supports middleware
- Server middleware → Query normalization: may include
- Query normalization → HTTP types: rewrites request
- Client conversion → Common conversion: uses conversions
- Common conversion → HTTP body: converts bodies
- Multipart streams → HTTP body: frames body data
- Event streams → HTTP body: streams body data
- Client conversion → Base value types: converts values