apple / apple/swift-openapi-generator
Support `oneOf` `required` sections
- Dominant language
- Swift
- Stars
- 2k
- Forks
- 182
- Avg merge
- 13h 28m
- Merged PRs (30d)
- 5
Description
### Description
As described in https://github.com/openai/openai-openapi/issues/391, the [OpenAI OpenAPI specification](https://github.com/openai/openai-openapi) contains the following `oneOf` `required` definitions:
```yaml
oneOf:
- required:
- vector_store_ids
- required:
- vector_stores
```
While not wrong in OpenAPI 3.0 or 3.1, the `swift-openapi-generator` doesn't properly recognize that `required` definition and produces the following warnings:
```
A property name only appears in the required list, but not in the properties map - this is likely a typo; skipping this property. [context: foundIn=Components.Schemas.CreateAssistantRequest.tool_resourcesPayload.file_searchPayload.Case1Payload (#/components/schemas/CreateAssistantRequest/tool_resources/file_search/case1)/vector_store_ids]
A property name only appears in the required list, but not in the properties map - this is likely a typo; skipping this property. [context: foundIn=Components.Schemas.CreateAssistantRequest.tool_resourcesPayload.file_searchPayload.Case2Payload (#/components/schemas/CreateAssistantRequest/tool_resources/file_search/case2)/vector_stores]
```
The `swift-openapi-generator` should support this valid syntax.
### Reproduction
The usage of the following [OpenAI OpenAPI spec](https://github.com/openai/openai-openapi) results in the `swift-openapi-generator` not properly recognizing the `required` definition and produces warnings.
A small excerpt of the relevant piece of the OpenAI OpenAPI spec:
```yaml
openapi: 3.0.0
# ...
tool_resources:
type: object
description: >
A set of resources that are used by the assistant's tools. The
resources are specific to the type of tool. For example, the
`code_interpreter` tool requires a list of file IDs, while the
`file_search` tool requires a list of vector store IDs.
properties:
code_interpreter:
type: object
properties:
file_ids:
type: array
description: >
A list of [file](/docs/api-reference/files) IDs made
available to the `code_interpreter` tool. There can be a
maximum of 20 files associated with the tool.
default: []
maxItems: 20
items:
type: string
file_search:
type: object
properties:
vector_store_ids:
type: array
description: >
The [vector store](/docs/api-reference/vector-stores/object)
attached to this assistant. There can be a maximum of 1
vector store attached to the assistant.
maxItems: 1
items:
type: string
vector_stores:
type: array
description: >
A helper to create a [vector
store](/docs/api-reference/vector-stores/object) with
file_ids and attach it to this assistant. There can be a
maximum of 1 vector store attached to the assistant.
maxItems: 1
items:
type: object
properties:
file_ids:
type: array
description: >
A list of [file](/docs/api-reference/files) IDs to add
to the vector store. There can be a maximum of 10000
files in a vector store.
maxItems: 10000
items:
type: string
chunking_strategy:
type: object
description: The chunking strategy used to chunk the file(s). If not set, will
use the `auto` strategy.
oneOf:
- type: object
title: Auto Chunking Strategy
description: The default strategy. This strategy currently uses a
`max_chunk_size_tokens` of `800` and
`chunk_overlap_tokens` of `400`.
additionalProperties: false
properties:
type:
type: string
description: Always `auto`.
enum:
- auto
x-stainless-const: true
required:
- type
- type: object
title: Static Chunking Strategy
additionalProperties: false
properties:
type:
type: string
description: Always `static`.
enum:
- static
x-stainless-const: true
static:
type: object
additionalProperties: false
properties:
max_chunk_size_tokens:
type: integer
minimum: 100
maximum: 4096
description: The maximum number of tokens in each chunk. The default value is
`800`. The minimum value is `100` and the
maximum value is `4096`.
chunk_overlap_tokens:
type: integer
description: >
The number of tokens that overlap between
chunks. The default value is `400`.
Note that the overlap must not exceed half
of `max_chunk_size_tokens`.
required:
- max_chunk_size_tokens
- chunk_overlap_tokens
required:
- type
- static
x-oaiExpandable: true
metadata:
$ref: "#/components/schemas/Metadata"
oneOf: # Syntax not recognized by the swift-openapi-generator
- required:
- vector_store_ids
- required:
- vector_stores
nullable: true
# ...
```
Swift Generator config:
```yaml
generate:
- types
- client
accessModifier: package
```
Results in the following warnings:
```
A property name only appears in the required list, but not in the properties map - this is likely a typo; skipping this property. [context: foundIn=Components.Schemas.CreateAssistantRequest.tool_resourcesPayload.file_searchPayload.Case1Payload (#/components/schemas/CreateAssistantRequest/tool_resources/file_search/case1)/vector_store_ids]
A property name only appears in the required list, but not in the properties map - this is likely a typo; skipping this property. [context: foundIn=Components.Schemas.CreateAssistantRequest.tool_resourcesPayload.file_searchPayload.Case2Payload (#/components/schemas/CreateAssistantRequest/tool_resources/file_search/case2)/vector_stores]
```
### Package version(s)
```console
├── swift-openapi-generator
│ ├── swift-algorithms
│ │ └── swift-numerics
│ ├── swift-collections
│ ├── openapikit
│ │ └── yams
│ ├── yams
│ └── swift-argument-parser
├── swift-openapi-runtime
│ └── swift-http-types
└── swift-openapi-urlsession
├── swift-openapi-runtime
│ └── swift-http-types
├── swift-http-types
└── swift-collections
```
### Expected behavior
The `oneOf` required definition should be properly recognized by the generator and used for the Swift output generation.
### Environment
```console
swift-driver version: 1.115.1 Apple Swift version 6.0.3 (swiftlang-6.0.3.1.10 clang-1600.0.30.1)
Target: arm64-apple-macosx15.0
```
### Additional information
_No response_
Contributor guide
Research direction
Start in the swift-openapi-generator code path that processes OpenAPI oneOf schemas and required properties, using the OpenAI specification excerpt as the reproduction. Verify the generated Swift output and warnings for the vector_store_ids/vector_stores cases; done means the valid oneOf required sections are recognized without the reported warnings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, swift
- Domain
- api, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100