Version control tracks revisions to code and configuration files so teams can review changes, recover earlier work, and collaborate without losing the change history. Git is one version control system. For an API, that history can cover the definition as well as the files used to document, test, and deploy it. section 1.2 section 8.2
Store OpenAPI definitions in a Git repository and treat it as their primary store. A dedicated repository makes definitions easier to discover and helps teams follow common patterns and reuse shared components. Design tools can read from and write to that repository rather than becoming the only place definitions live. This preserves Git-based review and CI/CD integration while leaving teams free to change editing tools. section 1.5.2 section 8.12.1
A practical change path is:
- Submit an API design change as a pull request so colleagues can inspect its history and review the proposal. section 1.5.2 section 8.2
- Run automated checks before human review. A minimum design review checklist can require an informative pull request, API linting, breaking-change checks, and prose linting for guide documentation. section 8.2
- Require governance approval before merging when that is part of the team's merge criteria. Passing automated checks establishes a review baseline; it does not replace approval. section 8.2
A review policy in practice
A team might require each pull-request title to cite a Jira ticket in the form DEV-XXXX, its description to explain why the change is needed, and its API definition to pass linting and breaking-change checks. A governance reviewer then approves the proposal before it joins the mainline branch. These are example team rules, not universal requirements. section 8.2
Version control also applies to declarative API gateway configuration, whether it sits in OpenAPI extensions, separate files, or Kubernetes manifests. Keeping those configurations as versioned files lets a team collaborate on the desired deployment state through Git workflows. section 1.5.5
