Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Refresh openapi.yaml and remove spec workarounds fixed upstream

Open
  • Is something wrong?
#463 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 3 days

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
58/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Active
Tech stack
git, openapi, swift
Domain
build-system, tooling

Research direction

Read Makefile, Scripts/prepare_openapi.py, and the three named workaround scripts, then run make generate to compare regenerated output. Remove the scripts and calls only if the output is unchanged; update the Makefile comment with fork commit 87d1f6f. Run swift package diagnose-api-breaking-changes on the regeneration diff and follow CONTRIBUTING.md under “Generated types” for any breaks.

Written by the indexing model from the issue text.

Description

The upstream openai-openapi spec has fixed three of the problems that Scripts/prepare_openapi.py works around. Against a fresh download of upstream openapi.yaml, each of these scripts is now a no-op:

Script Upstream state
Scripts/fix_rounded_int64_bounds.py Exact bounds (-9223372036854775808 / 9223372036854775807), no rounded values left
Scripts/fix_boolean_exclusive_minimum.py exclusiveMinimum is numeric everywhere, no boolean form left
Scripts/fix_recursive_reference.py No $recursiveRef left; CompoundFilter now references itself with a plain $ref

Tasks

  • Run make generate to refresh openapi.yaml and regenerate Components.swift
  • Remove the three scripts above and their calls in Scripts/prepare_openapi.py, after confirming the regenerated output is unchanged without them
  • Run swift package diagnose-api-breaking-changes on the regeneration diff and handle any breaks as described in CONTRIBUTING.md (Generated types)
  • Document fork commit 87d1f6f ("Unwrap nullable anyOf discriminator properties in oneOf switch cases") in the Makefile comment, which currently lists only the other three required generator changes

Workarounds that are still needed

Checked at the same time, for reference:

  • Generator fork, nullable anyOf: [T, {type: null}]: not supported upstream (apple/swift-openapi-generator#928, #931 and #933 closed unmerged; #831 open)
  • Generator fork, discriminators without mapping: openai/openai-openapi#542 still open; 138 unmapped discriminators have runtime values that differ from schema names
  • Generator fork, colliding discriminator values: message still collides in Item, ItemResource, RealtimeConversationItem, BetaItem and BetaItemResource
  • remove_unsupported_webhooks.py: the spec still has top-level webhooks; generator fix apple/swift-openapi-generator#734 is still open
  • remove_required_properties.py: all six entries are still required in the spec without being declared as properties
  • Typealias stripping in extract_components.py: still triggered (100 lines stripped on the last run)
Dominant language
Swift
Stars
2.9k
Forks
519
Avg merge
4d 9h
Merged PRs (30d)
13

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from MacPaw/OpenAI

All issues in MacPaw/OpenAI

Similar issues

More Swift issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.