Thanks for your interest in contributing! This project has an unusual shape:
almost all Swift code under Sources/ is generated, and the real source of
truth is the build pipeline. Please read this before opening a PR.
| Path | Edit by hand? |
|---|---|
Sources/*/Client.swift, Sources/*/Types.swift |
❌ Generated by swift-openapi-generator. Changes will be overwritten. |
Package.swift |
❌ Generated by Scripts/PackageBuilder.swift. |
.spi.yml |
❌ Generated by Scripts/SPIManifestBuilder.swift. |
Scripts/*.swift, Makefile |
✅ This is the actual source code. |
.github/** |
✅ CI workflows and composite actions. |
Sources/issues/Documentation.docc/** |
✅ DocC tutorial content. |
Tests/**, README.md, other docs |
✅ |
- The git submodule tracks github/rest-api-description.
Scripts/PackageTargetsParser.swiftreads the OpenAPI document'stags— each tag becomes one module (e.g.repos→GitHubRestAPIRepos).makegenerates per-tag generator configs, runs swift-openapi-generator, then regeneratesPackage.swiftand.spi.yml.- Dependabot bumps the submodule weekly; CI regenerates and auto-merges.
git clone --recurse-submodules https://github.com/Wei18/github-rest-api-swift-openapi.git
cd github-rest-api-swift-openapi
make # regenerate everything (clones and builds the generator on first run)
swift test # run the test suiteEach regenerated artifact is committed separately by make commit with the
message Commit via running: make <file> — please keep that convention.
- Mismatch between the Swift code and GitHub's actual API behavior → github/rest-api-description
- Problem with how code is generated → apple/swift-openapi-generator
- Problem with this repo's pipeline, packaging, or docs → open an issue here
- Keep changes minimal and focused; one concern per PR.
- Don't include regenerated
Sources/**churn in hand-written changes — CI regenerates sources on submodule updates. - Make sure
swift buildpasses for any target you touch.