Swagger (OpenAPI) files are the blueprints for your APIs, and just like any critical engineering document, they need to be versioned. While you can just git add and git commit them, that’s like throwing your blueprints into a filing cabinet and hoping for the best. True versioning means understanding the impact of changes and being able to roll back to a known good state with confidence.
Let’s see it in action. Imagine we have an openapi.yaml file defining a simple /users endpoint.
# openapi.yaml
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users:
get:
summary: Get a list of users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
Here’s that same spec, but now we’ve added a /users/{id} endpoint and a POST method to /users to create a new user.
# openapi.yaml (v1.1.0)
openapi: 3.0.0
info:
title: User API
version: 1.1.0
paths:
/users:
get:
summary: Get a list of users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
post:
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NewUser'
responses:
'201':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/users/{id}:
get:
summary: Get a user by ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: The ID of the user to retrieve
responses:
'200':
description: User found
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
name:
type: string
NewUser:
type: object
properties:
name:
type: string
The problem this solves is managing API evolution. As APIs grow and change, keeping track of which version of the spec corresponds to which deployed API version, and what those changes mean for consumers, becomes a nightmare without a robust system. Git, when used with best practices for API specs, provides that history, auditability, and rollback capability.
Internally, Git tracks changes as a series of snapshots. When you commit openapi.yaml, Git records the entire file’s state at that moment. A git diff shows you the delta between two snapshots, highlighting exactly what was added, removed, or modified. This is crucial for understanding the semantic impact of a change. Did you just rename a field (potentially breaking), or add a new optional field (backward compatible)?
The key levers you control are your Git branching strategy and commit messages. A common workflow is to have a main or master branch representing the stable, production-ready API spec. Feature branches are used for developing new endpoints or modifying existing ones. When a feature is complete and tested, it’s merged into main. Tagging specific commits on main with API version numbers (e.g., v1.0.0, v1.1.0) is essential. Your CI/CD pipeline can then use these tags to validate that the deployed API code matches the declared spec for that version.
Most people think of Git versioning as just a history log. The real power comes from integrating it with your API development lifecycle. For instance, you can use tools like Spectral to lint your OpenAPI files against custom rulesets before merging. This ensures consistency and adherence to your API design guidelines at every commit. Imagine a pre-commit hook that runs Spectral and prevents a merge if the OpenAPI spec violates a rule, like removing a required field. This proactive validation is a game-changer for maintaining API quality.
The next step is to integrate this versioned spec into your API documentation generation.