Spec-first Mode (Beta)

Spec-first Mode is for teams that want API specification files to be the source of truth. In this mode, you design and maintain OpenAPI or Swagger files directly in Apidog, preview the generated API documentation as you edit, and keep the files synchronized with Git.

Use Spec-first Mode when your team already works with YAML or JSON specification files, reviews API changes through Git, or wants API design to fit naturally into a code repository workflow.

How Spec-first Mode Works

In a regular Apidog project, APIs are usually created and edited through visual forms. In a Spec-first project, the primary workspace is file-based.

You work with files such as:

openapi.yaml

openapi.json

Swagger 2.0 files

Markdown files and other supporting project files

Apidog parses the specification files and turns them into a navigable API structure. You can edit the raw files, use supported visual forms, validate the specification, preview generated documentation, and push changes back to Git.

Create a Spec-first Project

Click + New Project.

In the project type selector, choose Spec-first Mode.

Connect a Git provider, such as GitHub, GitLab, Azure DevOps, or Bitbucket.

Select an organization or workspace, then choose an existing repository or create a new repository if the option is available.

Select the main branch Apidog should synchronize with.

Choose whether to install a webhook.

Installing a webhook allows pushes in the Git repository to trigger automatic synchronization. This usually requires admin permission on the repository. If you do not have admin permission, you can skip webhook installation and sync manually.

Enter the project name, configure member permissions, and click Create.

After creation, Apidog performs the first synchronization. If the repository's default branch is not main, Apidog uses the repository branch name for the project main branch.

Spec-first projects do not include sample project data. The API content comes from your specification files.

The Specs Workspace

Spec-first projects include a Specs workspace in the left sidebar. This is the main place to manage specification files and Git sync.

The workspace contains three main areas:

File explorer: Browse and manage files and folders from the synchronized repository.

API structure tree: Navigate parsed OpenAPI content, such as overview, endpoints, schemas, and definitions.

Editor: Edit files in code view or, for supported OpenAPI nodes, in form view.

When you select an endpoint, schema, or other supported node in the structure tree, Apidog opens the related part of the source file. This lets you move between the file-level view and the API-level view without leaving the Specs workspace.

Edit Specification Files

The editor supports different file types and editing modes.

Code View

Use Code view to edit YAML, JSON, Markdown, and other text files directly. This is the default way to work in Spec-first Mode.

Form View

For supported OpenAPI nodes, Apidog also provides a Form view. This lets you edit common API fields through structured controls while keeping the underlying specification file as the source of truth.

Form view is available for supported nodes such as:

API overview

Endpoints

Schemas

Definitions

If the selected file or node cannot be edited in form view, Apidog keeps you in code view.

Validate and Preview While Editing

Spec-first Mode includes validation and preview tools in the editor header.

Validation

The Validation panel shows issues detected in the current specification, including warnings and errors. The validation badge displays the total number of detected issues.

Use this panel to find syntax problems, missing required fields, and rule violations before committing changes.

Preview

The Preview panel shows how the selected specification node will appear in generated API documentation.

Preview is available for:

API overview

Endpoints

Schemas

Definitions

For endpoints, Preview includes:

Docs: The generated endpoint documentation.

Try it out: A request panel for sending a request based on the selected endpoint definition.

For schemas, definitions, and overview nodes, Preview shows the generated documentation view.

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

Sync Changes from Git

When other team members push changes to the connected repository, you can pull the latest files into Apidog.

Open the Specs workspace.

Click the current branch name in the Specs sidebar.

Click Git Pull.

If webhook sync is installed, Apidog can also receive push events from the Git provider and trigger synchronization automatically.

Commit and Push Changes to Git

After editing files in Apidog, push your changes back to the connected repository.

Edit one or more files in the Specs workspace.

Click Changes to review modified, added, renamed, and deleted files.

Click Commit & Push.

In the Push to Git repo modal, select the files you want to include.

Enter a commit message.

Click Push.

If you do not want to keep your local edits, use Discard all changes before pushing.

Manage Branches

Spec-first Mode supports branch-based collaboration. Apidog maps synchronized Git branches to project branches so you can switch between versions of the specification.

Switch Branches

Click the branch name in the Specs sidebar and select another branch from the dropdown.

Track an Existing Git Branch

If a branch exists in Git but has not been imported into Apidog, click Import New Branch, select the branch, and import it. Apidog then starts tracking and synchronizing that branch.

Create a Branch

Open Project Settings > Git & Branches and click New Branch to create a branch from an existing project branch.

Re-sync a Branch

If a branch sync fails or the files look out of date, use Re-sync in Project Settings > Git & Branches. This resets the sync state for that branch and imports the files again.

View Sync Logs

If a sync fails, open the branch actions and choose View Logs to inspect the sync details.

Stop Tracking or Delete a Branch

Deleting a tracked branch removes it from Apidog's sync configuration. For non-main branches, the project branch record can also be removed.

Webhook Sync and Permissions

Webhook sync is optional but recommended for teams that want Apidog to stay up to date with repository pushes.

When webhook sync is enabled:

Apidog registers a webhook on the connected Git provider.

Only supported push events are processed.

Apidog verifies the webhook signature or token before syncing.

Permission requirements:

Installing a webhook usually requires repository admin permission.

Pushing changes requires write permission.

If webhook installation is skipped, manual sync is still available.

If you skipped webhook installation during project creation, you can install it later from Project Settings > Git & Branches.

Storage-backed Spec-first Projects

Some Spec-first projects may use Apidog's internal storage instead of an external Git repository.

These projects still use the Specs workspace, file-based editing, validation, preview, and branch management.

The UI labels are slightly different:

Git Pull appears as Sync.

Commit & Push appears as Save.

Git provider information and external webhook settings are hidden.

Notes and Limitations

Spec-first Mode is currently in beta.

The Specs workspace appears only in Spec-first projects.

Spec-first projects do not create sample API data.

The specification file is the source of truth. Changes should be made through the Specs workspace or synchronized through Git.

Webhook installation may fail if you do not have enough repository permission. You can still use manual sync if you have write access.

Spec-first Mode (Beta)

How Spec-first Mode Works#

Create a Spec-first Project#

The Specs Workspace#

Edit Specification Files#

Code View#

Form View#

Validate and Preview While Editing#

Validation#

Preview#

Sync Changes from Git#

Commit and Push Changes to Git#

Manage Branches#

Switch Branches#

Track an Existing Git Branch#

Create a Branch#

Re-sync a Branch#

View Sync Logs#

Stop Tracking or Delete a Branch#

Webhook Sync and Permissions#

Storage-backed Spec-first Projects#

Notes and Limitations#