DEV Community

Cover image for I Spent a Morning With Apidog's Spec-First Mode. The Visual Designer Is No Longer the Only Adult in the Room.
Hassann
Hassann

Posted on • Originally published at apidog.com

I Spent a Morning With Apidog's Spec-First Mode. The Visual Designer Is No Longer the Only Adult in the Room.

There are two common API workflows: keep the OpenAPI spec in Git and edit it directly, or design APIs visually and export the spec when needed.

Try Apidog today

Both workflows can work, but they optimize for different things. Git-first specs are slower at the beginning and easier to trust later. Visual API design is faster to start, but teams often end up reconciling drift between “the spec in the tool” and “the spec in the repo.”

Apidog’s visual designer has long been useful for the second workflow. With Spec-First Mode (Beta), it now supports the first one more directly: your OpenAPI files stay in Git, and Apidog becomes an editor and collaboration layer on top of those files.

I tested the beta against an OpenAPI spec from a side project. Here is how it works, where it fits, and what to check before using it with a team.

What Spec-First Mode changes

Apidog now has two project modes:

  • General Mode: build APIs through visual forms; Apidog generates the OpenAPI spec.
  • Spec-First Mode: edit raw .yaml and .json OpenAPI files directly; sync those files with Git.

In Spec-First Mode, the OpenAPI file is the source of truth. The UI does not wrap the spec in a separate internal model. Instead, it gives you:

  • a code editor for OpenAPI YAML/JSON
  • OpenAPI schema-aware autocomplete
  • syntax highlighting
  • a live endpoint outline generated from your files
  • two-way Git sync
  • commit and push from inside Apidog

The important shift is ownership: the artifact is the file in your repository.

The Spec-First Mode workspace, mid-edit on a pet-store project. The left sidebar is the auto-generated path outline — note Paths (224) at the top, then individual routes like /store/auth/{email}, /admin/auth, /store/token materializing straight from the file. Top right: the Changes (1) indicator and the green Commit & Push button. Bottom-left: Synced just now — the sync status indicator the prose references later.

The endpoint outline is especially useful. YAML itself is not the hard part of OpenAPI; navigating a large spec is. The live outline gives you visual navigation without forcing you out of the file-based workflow.

Set up a Spec-First project

The setup is short. Most of the time is spent authorizing Git access.

1. Create a new Spec-First project

From the Apidog projects screen:

+ New Project → General → Spec-first Mode
Enter fullscreen mode Exit fullscreen mode

Be careful here: General Mode is marked as “Recommended,” so it is easy to miss the Spec-first Mode tile if you usually create projects quickly.

2. Connect a Git repository

In the same dialog, scroll to Connect with Git Repository.

Authorize your Git provider, then choose:

  • Organization
  • Repository
  • Main branch

Apidog uses the selected branch as the working source for your OpenAPI files.

3. Configure the project

Set:

  • Project Name
  • team permissions
  • repository connection

Then click Create.

On the first sync, Apidog pulls the .yaml and .json files from the repository into the workspace.

Steps 1–3 live in the same dialog. Top: the two mode tiles. General Mode is flagged Recommended, which is what makes the Spec-first Mode tile (right, Beta badge, purple highlight) the easy thing to miss. The Spec-first tile lists what changes underneath: OpenAPI Spec Editor (Supports Visualization) and Two-way sync with Git repository. Bottom: the Connect with Git Repository panel with Organization, Repository (pet-store), and Main branch (main) dropdowns, plus the Project Name field. One screen, three decisions.

Edit the OpenAPI file

Open one of the YAML or JSON files from the synced repo.

You can edit it like a normal OpenAPI file:

paths:
  /store/token:
    post:
      summary: Create store access token
      operationId: createStoreToken
      responses:
        '200':
          description: Token created
Enter fullscreen mode Exit fullscreen mode

As you type, Apidog parses the file and updates the endpoint outline in the sidebar.

That makes the workflow closer to using VS Code with an OpenAPI extension, but with built-in project navigation and Git sync. Clicking an endpoint in the outline jumps to the corresponding location in the file.

Commit and push changes

When you are ready to save changes back to the repository:

  1. Click Commit & Push in the top-right corner.
  2. Review the Changes list.
  3. Enter a commit message.
  4. Click Push.

There is no separate staging step. Files shown in Changes are included in the commit.

The Push to Git repo dialog. Note the structure: one Commit Message field, a Changes (1 file) list with a checkbox per file, and three buttons at the bottom — Discard all changes (left, destructive), Cancel (neutral), and Push (the primary action, purple). In the background you can see the Commit & Push button at the top right of the workspace that opened this dialog.

For spec edits, that simplification works well. Most changes are small, file-based, and intended to move together.

Watch the sync status

The sync indicator in the bottom-left corner is worth paying attention to.

It tells you whether the Apidog workspace is:

  • synced with the remote branch
  • ahead with local changes
  • behind the remote branch
  • out of sync

During testing, I edited the same file locally, pushed from the terminal, and kept Apidog open. Apidog detected that the remote had changed and marked the workspace as behind. One click pulled the update into the editor.

That is the key behavior for mixed-tool teams. One developer can keep using Vim or VS Code, another can use Apidog, and both are still editing the same Git-backed OpenAPI file.

What to know before adopting it

Spec-First Mode is useful, but it is not just a toggle on an existing Apidog project.

You cannot switch modes later

A project created in Spec-First Mode stays spec-first. A project created in General Mode stays visual-first.

That is intentional because the underlying project models are different, but it matters when planning a team workflow.

If some teammates need the visual designer and others need raw spec editing, the practical approach is:

  1. keep the OpenAPI spec in Git
  2. create a Spec-First project connected to that repo
  3. let visual-mode users work from a separate project that imports from the same source

That is workable, but not seamless.

The outline updates in real time

The live parsing was faster than expected. Adding or editing paths updated the sidebar almost immediately.

This matters because the outline becomes a navigation tool, not just a delayed validation result.

Git sync is central to the workflow

Spec-First Mode is not “export OpenAPI when done.” It is built around bidirectional Git sync.

That makes it a better fit for teams where CI, SDK generation, documentation, or contract tests already depend on the spec in the repository.

When Spec-First Mode fits

Use Spec-First Mode if your team already treats OpenAPI as a source-controlled artifact.

Good fits include teams that:

  • write OpenAPI YAML or JSON by hand
  • run spectral lint in CI
  • generate client SDKs from the spec
  • generate server stubs from the spec
  • review API changes through pull requests
  • want Apidog navigation and collaboration without giving up Git
  • currently rely on manual export steps from a visual API tool

It is also useful when developers want keyboard-first editing, but the broader team still benefits from an API platform UI.

When to stay with General Mode

Use Apidog’s default General Mode if your team mainly contributes through forms and visual API design.

Spec-First Mode assumes contributors are comfortable with OpenAPI structure. That is a good tradeoff for API-heavy teams, but not for teams where the visual designer is what makes API contribution accessible.

It is also not ideal yet if you need one project where users freely switch between raw spec editing and visual design.

Takeaway

Spec-first API development used to mean giving up API design tools. Visual API platforms usually worked best when they owned the API model and exported OpenAPI later.

Apidog’s Spec-First Mode changes that workflow. The repo file remains the source of truth, while Apidog provides editing, navigation, autocomplete, and Git sync around it.

If your OpenAPI spec already lives in Git, create a Spec-First project, connect the repository, make a small change, and push it back. The first commit should take minutes. The real test is whether the workflow still feels reliable after a week of normal team edits.

Top comments (0)