[zac]

Summary

Adds an OpenAPI → Endpoints generator as a SwiftPM build tool plugin. You put Petstore.openapi.yaml in a target, and every build generates the server, models, and endpoints for that API. Output is deterministic: the same spec, config, file stem, and generator version produce byte-identical files on any machine or OS. It also adds the small set of runtime hooks the generated code needs.

Changes

Package

• Swift tools 6.1. A default-on OpenAPIGenerator trait guards the generator's dependencies, OpenAPIKit 6.4.0 and Yams 6.2.2, both pinned exactly. Apps that only use the runtime can pass traits: [], and on SwiftPM 6.2+ they then don't fetch either package. With the trait off, the CLI is a stub that tells you to enable it.
• New products and targets: the EndpointsGeneratorPlugin product, the EndpointsGeneratorCore target, the endpoints-generate CLI, and two test targets.

Generator (Sources/EndpointsGeneratorCore)

• Pipeline: loader (3.0 specs are converted to 3.1) → validation → IR → naming → rendering into four fixed files per spec. Diagnostics carry file:line:col and the JSON pointer.

• Naming is a frozen, ASCII-only contract. Collisions and reserved names are errors that point you to a renames entry in the optional <Stem>.endpoints.json config. There's no auto-suffixing.

• Mapping covered so far:

  • Servers and environments.
  • Object schemas. Properties keep spec order, and required-nullable fields encode an explicit null.
  • Open enums by default, with closed enums as a config option.
  • Typed path, query, and header parameters, including arrays and optional headers.
  • JSON bodies.
  • Status-tagged Response and ErrorResponse enums.
  • RFC 3339 dates.

  Constructs not mapped yet (oneOf/anyOf/allOf, recursion, multipart and form bodies) report "unsupported", which is an error by default and a warning with strict: false.

Runtime hooks (Sources/Endpoints, all additive)

• DecoderType.decode(_:from:response:) with a default implementation, plus the CodingUserInfoKey.httpStatusCode and .httpHeaders keys.
• HTTPResponseJSONDecoder: configures a fresh JSONDecoder for each call, decodes an empty body as null, and can decode selected statuses as Data.
• MultiValueParameterRepresentable: arrays are sent as repeated query or form items. If you already have your own ParameterRepresentable conformance, it still wins.
• Int32, Int64, UUID, and RawRepresentable types work as path and query parameters.

Docs

• docs/OpenAPIGenerator-Design.md (design and decisions) and docs/OpenAPIGenerator-SSE.md (an accepted design for Server-Sent Events behind a default-off ServerSentEvents trait, planned as a later phase).
• Verification records, updated DocC and Examples, and a "Migrating from 0.5" section in the README.

Behaviour changes for existing users

• Swift 6.1 is now the minimum.
• If you declared your own UUID, Int32, or Int64 parameter conformances, delete them. Swift now warns that they're redundant, and request building uses the library's version. A UUID is sent as uuidString (uppercase).

Naming and configuration

• Idiomatic names by default. IN_PROGRESS becomes .inProgress, pet_record becomes PetRecord, owner_name becomes ownerName, and get_pet_by_id becomes GetPetByIdEndpoint. Wire names never change: CodingKeys and raw values keep the server spelling.

• A typed Swift configuration file, <Stem>.endpoints.swift, in the target. It's type-checked by Xcode, and the generator evaluates it at build time with no extra steps:

  // endpoints-configuration-version: 1
  import EndpointsGeneratorConfig
  
  let petstoreConfiguration = EndpointsConfiguration(
      namespace: "PetStore",
      accessLevel: .public,
      enumCaseNamingStrategy: .verbatim,
      operationNamingStrategy: .custom { $0.removingPrefix("legacy_").upperCamelCased },
      acronyms: ["ID", "URL"],
      renames: [.property("owner_name", in: "Pet"): "owner"]
  )

  It supports per-category strategies (.verbatim, .camelCase, .upperCamelCase and .custom), typed renames with parameter locations, and x-swift-name/x-enum-varnames. Collisions and invalid names are errors, and unused renames are warnings.

• Determinism for configs that run code. A pre-compile check rejects extra imports, # directives, regex literals, key paths, and nondeterministic standard-library APIs. The config program runs with an empty environment and deterministic hashing, and every evaluation runs it twice in separate processes and requires identical results.

• Verification: macOS with the plugin sandbox on, Linux swift:6.1 (175 tests), and native Xcode macOS and iOS simulator targets. Native Xcode re-runs the generate step on every build, because Xcode gives the plugin command a new script GUID each time. The cached run takes about 0.2 s and leaves outputs untouched.

• Docs: a new Generating DocC article and a README quick start.

Relationship to #24

The path-building fixes from #24 are now in main. With them in place, embedded path templates such as /files/{id}.json encode each value as its own segment through an internal EncodedPath type.

Two tests are wrapped in withKnownIssue for runtime bugs that are still to be fixed separately:

• optionalHeadersOmitNilAndDescribePresentValues: optional header components throw invalidHeader instead of being omitted.
• emptyBodyErrorUsesDefaultEmptyCodable: an empty error body fails to decode as EmptyCodable.

Each wrapper starts failing once its fix lands, which flags it for removal.

Testing

• macOS (Swift 6.4): swift build --build-tests -Xswiftc -warnings-as-errors is clean, and all suites pass with exactly the 2 known issues. Generated code produces zero warnings.
• Linux (swift:6.1 in Docker): builds, and 122 tests pass with the same 2 known issues.
• Determinism: compiled golden files compared byte-for-byte, generation in separate processes with randomized hash seeds, a banned-API lint, and a 20-level shared-schema graph that generates in about 0.1 s.
• End to end: Examples/PetstoreClient (two modules, a public auth extension, a status-union endpoint) builds and tests with the plugin sandbox on, and Examples/RuntimeOnlyClient (traits: []) resolves without OpenAPIKit or Yams.
• Each phase was reviewed until it passed: the foundation took four rounds, the runtime hooks three.
• Not yet checked: a native .xcodeproj using the plugin.

Coverage (line, macOS)

• EndpointsGeneratorCore: 94.0%. The lowest file is SecurityDocumentation.swift at 71.7%.
• Endpoints runtime: 76.0% overall. The new files are well covered; the low spots are older code (Server.swift 10%, URLSession+Endpoints.swift 45%, MultipartFormEncoder.swift 47%).