apple / apple/swift-openapi-generator
Support nullable referenced schemas using anyOf with type: null
- Dominant language
- Swift
- Stars
- 2k
- Forks
- 182
- Avg merge
- 13h 28m
- Merged PRs (30d)
- 5
Description
### Description
When an OpenAPI 3.1 schema uses `anyOf` with a `$ref` and a `type: "null"` branch, Swift OpenAPI Generator does not appear to generate the expected optional Swift property.
Minimal schema:
```yaml
openapi: 3.1.0
info:
title: Repro
version: 1.0.0
paths: {}
components:
schemas:
Parent:
type: object
properties:
child:
anyOf:
- $ref: '#/components/schemas/Child'
- type: 'null'
required:
- child
Child:
type: object
properties:
name:
type: string
required:
- name
```
### Expected behavior
The generated Swift type for `Parent` should allow `child` to be decoded/encoded as a nullable referenced object, for example as an optional `Child`-like generated property.
### Actual behavior
The generator did not produce a usable optional property for this schema shape in my project. I had to switch to this workaround:
```yaml
child:
allOf:
- $ref: '#/components/schemas/Child'
nullable: true
```
That workaround generates a usable optional Swift property, but it also emits warnings because `nullable` is not part of the OpenAPI 3.1 schema vocabulary:
```text
Found 'nullable' property. This property is not supported by OpenAPI v3.1.0.
OpenAPIKit has translated it into 'type: ["null", ...]'.
```
### Why this matters
OpenAPI 3.1 supports JSON Schema's `null` type, so `anyOf`/`oneOf` with a `type: "null"` branch is a common way to express a nullable `$ref`. It would be useful if Swift OpenAPI Generator supported this directly, or documented the recommended schema shape for nullable referenced objects.
### Environment
- Swift OpenAPI Generator: 1.12.0
- OpenAPI document version: 3.1.0
- Swift toolchain: Xcode toolchain, Swift 6.x
Contributor guide
Research direction
Start by running Swift OpenAPI Generator 1.12.0 against the minimal OpenAPI 3.1 schema in the issue and inspect the generated Parent and Child types. Trace how the anyOf branches containing a $ref and type: "null" are handled, then verify that child is a usable nullable Child-like property without requiring the nullable workaround.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- api, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 70/100