Hassann

Posted on Jun 10 • Originally published at apidog.com

Git-native Collaboration for API Testing and Engineering

Your OpenAPI spec is the contract between your API and its consumers. The important question is: does that contract live where your team actually works?

Try Apidog today

Too often, API specifications sit in isolated tools—exported once, forgotten, and rarely updated when the implementation changes. Documentation drifts. Test collections diverge. Reviewers approve code changes without seeing the corresponding spec updates.

Spec-first Mode flips that workflow. Your OpenAPI or Swagger files become the source of truth, stored directly in your Git repository alongside implementation code. Every spec change moves through the same branches, pull requests, and reviews you already use. API design, testing, and documentation stay synchronized.

This guide walks through how to set up a Spec-first project in Apidog, edit OpenAPI files with your team, and keep the spec aligned with your Git workflow.

What is Spec-first Mode?

In a typical API project, you create endpoints through visual forms or import an existing spec as a starting point. The tool stores API definitions internally, and Git integration—if available—is often an export/import step.

Spec-first Mode uses a file-based workflow:

openapi.yaml or openapi.json lives in your repo
Apidog parses the file and generates a navigable API structure
You edit the source files directly or through supported forms
Changes sync back to Git

The specification file stays authoritative. Apidog reads from it, writes to it, and keeps it synchronized with your repository.

Prerequisites

To follow along, you need:

An Apidog account
A Git repository with an OpenAPI/Swagger file, or an empty repo to start fresh
Write access to the repository
Basic familiarity with OpenAPI or Swagger syntax

Step 1: Create a Spec-first Project

In Apidog:

Click + New Project
Choose Spec-first Mode
Connect your Git provider
Select the repository and branch you want to sync

Supported Git providers include:

GitHub
GitLab
Azure DevOps
Bitbucket

Apidog syncs with your repository’s default branch. If the default branch is not named main, Apidog adapts automatically.

Step 2: Configure Webhook Sync

During setup, Apidog can install a webhook for automatic sync.

Note: Webhook installation usually requires admin permission on the repository. If you do not have admin access, skip this step and use Git Pull manually.

With webhook sync enabled:

A teammate pushes a spec update
Apidog receives the repository event
The project syncs automatically
Everyone sees the latest spec state

If you skip webhook setup during project creation, add it later from:

Project Settings > Git & Branches

Step 3: Explore the Specs Workspace

After project creation, Apidog opens the Specs workspace. This is where you edit files, inspect parsed OpenAPI content, and perform Git operations.

The workspace has three main areas:

Panel	What it shows
File Explorer	Files and folders from your synced repository
API Structure Tree	Parsed OpenAPI content: endpoints, schemas, definitions, and overview
Editor	Code view or form view for editing files

A useful workflow:

Click an endpoint in the API Structure Tree
Apidog highlights the corresponding section in the source file
Edit the YAML or JSON directly
Validate and preview the result before committing

This lets you move between a high-level API view and the underlying OpenAPI source without switching tools.

Step 4: Edit Your Specification Files

Code View: Edit YAML, JSON, and Markdown Directly

Use Code view for raw file editing.

For example, you can update an endpoint directly in openapi.yaml:

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User found

Your edits remain in the file. Apidog does not transform the spec into a separate internal format. The OpenAPI file remains the single source of truth.

Form View: Edit Supported OpenAPI Nodes Visually

For supported OpenAPI nodes, switch to Form view.

Form view is useful when you want to:

Add endpoints without memorizing every YAML field
Edit schemas visually
Update API metadata
Configure security definitions

If a node does not support form editing, Apidog keeps you in code view.

Step 5: Validate and Preview Before Committing

Spec-first Mode includes validation and documentation preview inside the editor.

Validate the Spec

Click Validation in the editor header.

The validation panel shows warnings and errors for the current spec. Use it to catch issues such as:

YAML or JSON syntax errors
Missing required OpenAPI fields
Schema violations
Naming convention problems

Fix validation issues before pushing so reviewers can focus on the API change itself instead of basic spec errors.

Preview Generated API Documentation

Click Preview to see how the spec renders as documentation.

For endpoints, preview includes:

Tab	Content
Docs	Generated endpoint documentation
Try it out	Live request panel based on the endpoint definition

For schemas and definitions, preview shows the rendered documentation view.

Validation and Preview share the same side panel. Opening one automatically closes the other.

Step 6: Pull Updates from Your Team

When collaborators push spec changes to Git, bring them into Apidog from the Specs workspace:

Open the Specs workspace
Click the current branch name in the sidebar
Select Git Pull

If webhook sync is active, Apidog pulls changes automatically when the repository receives push events.

Use this step before starting new edits to avoid working against an outdated spec.

Step 7: Commit and Push Your Changes

After editing files in Apidog, send your updates back to Git:

Make changes in the Specs workspace
Click Changes in the sidebar
Review modified, added, renamed, and deleted files
Click Commit & Push
Select the files to include
Write a commit message
Click Push

Example commit message:

Update user lookup endpoint response schema

Your spec updates now appear in the same Git workflow as your code changes. Teammates can review implementation and API contract changes together in pull requests.

Tip: Use Discard all changes if you want to abandon local edits before pushing.

Step 8: Work with Branches

Spec-first Mode supports branch-based collaboration. Apidog maps Git branches to project branches, so you can switch between different spec versions.

Common branch operations:

Action	How to do it
Switch branches	Click branch name, then select another branch
Import existing Git branch	Click Import New Branch, select the branch, then import
Create new branch	Go to Project Settings > Git & Branches, then click New Branch
Fix sync issues	Use Re-sync in branch settings
View sync logs	Open branch actions, then click View Logs

Use branches the same way you do in Git:

Feature branches for new endpoints
Release branches for versioned API changes
Hotfix branches for urgent spec corrections
Parallel branches for experimental API designs

Step 9: Integrate Specs with CI/CD

Because your specs live in Git, they can pass through the same automation pipeline as application code.

Common CI/CD tasks include:

Lint specs on every PR using Apidog validation or tools like Spectral
Generate documentation when specs merge to main
Run API tests triggered by spec changes
Sync specs to downstream systems, such as API gateways, mock servers, or SDK generators

Example GitHub Actions workflow:

name: Validate and Test API Spec

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Lint OpenAPI Spec
        run: npx spectral lint openapi.yaml

      - name: Run API Tests
        run: apidog run tests --spec openapi.yaml

This makes the OpenAPI file part of your quality gate instead of a separate artifact updated after the fact.

Alternative: Use a Storage-backed Project

If you are not ready to connect an external Git repository, Apidog also supports storage-backed Spec-first projects.

These projects use Apidog’s internal storage but still support:

File-based editing
Validation and preview
Branch management

The main UI labels change slightly:

Git-backed project	Storage-backed project
Git Pull	Sync
Commit & Push	Save

You can migrate to external Git when your team is ready.

Summary

Spec-first Mode changes the API workflow from tool-centered to Git-centered:

Before Spec-first	After Spec-first
Specs live in a separate tool	Specs live in your Git repo
Export/import is required to sync	Sync happens through Git
Reviews happen outside code review	Reviews happen in pull requests
Documentation is generated separately	Documentation can be previewed while editing
Tests are disconnected from spec changes	Tests can be triggered by spec updates

Spec-first Mode makes OpenAPI files the contract they should be: versioned, reviewed, and aligned with your code.

To try it, create a Spec-first project in Apidog and connect your first repository.

DEV Community