How to Keep OpenAPI Documentation in Sync with GitHub

Commit the complete Payments API JSON document from the creation guide as openapi.json. Choose the branch that represents the contract your team should consume. Review specification changes in pull requests alongside implementation changes.

If you prefer YAML, the GitHub workflow supports JSON or YAML specification files, with YAML aliases unsupported. Local file upload is a separate JSON-only workflow. Keep credentials out of the specification and repository URLs.

repository/
  openapi.json
  src/
  tests/

Example source selection:
branch: main
file: openapi.json
operation: POST /payments

In Settings > API Source, connect a GitHub integration whose installation has repository access. Select the repository, branch and specification file. Preview the definition and confirm POST /payments appears before saving the source.

REST Test normalizes the imported operations for authenticated workspace Documentation, API Designer, Request Builder and SDK Generation. This is not public hosted workspace documentation. Account membership alone does not grant access to every Workspace.

Commit a specification change, then run a manual source check. Inspect added, modified and removed operations before applying the update. For example, adding currency to a required list means existing payment callers must start sending it.

Compare local and incoming changes when API Designer edits overlap with the source. Use the supported conflict-resolution controls to choose the intended values before applying the update. Definition diffs are not guaranteed breaking-change detection; run caller tests separately.

Before: required: ["amount"]
After:  required: ["amount", "currency"]

Caller to review:
POST /payments
{"amount":4900}

Updated caller:
POST /payments
{"amount":4900,"currency":"EUR"}

Automatic source checks and automatic application are separate settings. Start with manual review, then choose a check interval allowed by the account plan. Manual and automatic source-check allowances are shared across the account. Inspect the current Pricing catalog rather than assuming unlimited checks.

Synchronization imports repository changes into REST Test. It does not automatically commit or push local API Designer edits back to GitHub. If a local design should become the repository contract, export saved JSON, review the diff in your own repository workflow and commit it deliberately.

Inspect available definition revisions when investigating an update. History depends on retained revisions and account plan retention; it is not a permanent audit archive.

If a repository is missing, inspect GitHub App installation access. If a branch or file is missing, check the selected branch and path. Validate JSON or YAML syntax and the supported OpenAPI or Swagger version when preview fails. Replace YAML aliases with explicit values for this workflow.

For stale documentation, confirm that the commit reached the selected branch, run a source check and inspect pending changes or conflicts. For stopped automatic checks, review source errors, schedule settings and account usage. Never paste installation credentials or repository tokens into a support message.