What Is Apidog Spec-First Mode?

Apidog Spec-First Mode is a beta workspace for teams that treat their OpenAPI spec as source code. You edit openapi.yaml or openapi.json directly in an IDE-style YAML/JSON editor, then sync changes both ways with a connected Git repository. There is no form editor between you and the file: the spec is the project.

Try Apidog today

This guide shows how Spec-First Mode works, how to set it up, how to use it in a daily Git workflow, and what to expect from the beta. For the broader workflow behind this approach, see the git-native API workflow.

What is Apidog Spec-First Mode?

Spec-First Mode is a beta editing mode in Apidog where your API design lives as a raw OpenAPI document. You open the file, edit YAML or JSON, validate it, commit it, and push it to Git.

Apidog keeps the spec and the repository in sync in both directions:

• Pull a teammate’s change and your editor updates.
• Edit the spec in Apidog and push it back to the repo.
• Keep Git as the shared source of truth for history, review, and branching.

This mode is built for teams that already run a native Git workflow: backend engineers, platform teams, and API-first teams that version API contracts through pull requests. Instead of hiding the spec behind forms, Spec-First Mode shows you the file directly.

Spec-First Mode vs Design-First Mode

Apidog has two modes:

• Design-First Mode: a visual, form-based API design experience.
• Spec-First Mode: a raw OpenAPI editor connected to Git.

For a deeper comparison, read the spec-first vs design-first comparison.

Aspect	Design-First Mode	Spec-First Mode Beta
Primary editor	Visual forms and UI panels	Raw YAML/JSON code editor
Source of truth	Apidog project database	Spec file in your Git repo
Git sync	Export/import based	Native two-way sync
Best for	Visual designers, mixed teams	Git-native engineering teams
Learning curve	Gentle, guided	Familiar if you know OpenAPI

Neither mode is universally better. Use the one that matches how your team actually designs and reviews APIs.

Key features

Spec-First Mode combines a code editor, OpenAPI-aware navigation, Git sync, change tracking, and team permissions.

IDE-style OpenAPI editor

The center of the workspace is a code editor for your OpenAPI document. You edit the raw YAML or JSON directly.

The editor supports:

• Syntax highlighting for OpenAPI YAML and JSON
• Schema validation while you type
• Auto-completion for OpenAPI and Swagger keywords
• Direct editing of paths, operations, schemas, parameters, and responses

For example, you can define an operation directly in YAML:

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Auto-completion is useful when you are deep in a schema and need the correct OpenAPI keyword, such as additionalProperties, oneOf, allOf, or $ref.

Auto-parsed navigable outline

Large OpenAPI files get difficult to scan quickly. Spec-First Mode parses the document and builds a navigable outline in the sidebar.

You can use the outline to jump to:

• Paths
• Operations
• Schemas
• Components

Instead of scrolling through thousands of lines, you can click directly into something like POST /orders or components.schemas.Invoice.

The outline updates as the spec changes, so it reflects the current file instead of a stale generated view.

Two-way Git sync

Two-way Git sync is the core workflow.

Spec-First Mode connects your OpenAPI spec to a Git repository and syncs changes in both directions:

• Pull repository changes into Apidog.
• Edit the spec in Apidog.
• Commit your changes.
• Push them back to the connected repository.

Supported connection options:

Provider	How it connects
GitHub	Direct integration
GitLab	Direct integration
Azure DevOps	Via generic Git Connection

Azure DevOps works through a generic Git Connection using standard Git credentials.

For a provider-specific walkthrough, see the sync OpenAPI spec to GitHub guide.

Commit, push, and sync status

Spec-First Mode follows the Git workflow developers already use.

After editing the spec, you can:

1. Review the changed files.
2. Write a commit message.
3. Commit the change.
4. Push it to the connected repository.

A sync status indicator shows whether your local spec is up to date with the repo. For example, it can show when the project is synced or when you still have unpushed work.

This removes ambiguity. You can tell whether the version in Apidog matches the version your teammates will see in Git.

File change tracking

Before committing, Spec-First Mode shows what changed at the file level.

Changes are marked as:

• Modified
• Added
• Deleted

Use this as a checkpoint before committing. If an experiment should not be shared, discard the unpushed edit before it reaches the repository.

This keeps your Git history cleaner and prevents accidental API contract changes from being pushed.

Branch and repo-scoped projects

A Spec-First project is created from a specific repository and branch, usually main.

That means the Apidog project points to a real Git location:

• Repository
• Branch
• Spec file
• Commit history

During setup, you also configure team permissions so the right people can access and modify the project.

How to set up Spec-First Mode

Follow this setup flow.

The official walkthrough is available in the Spec-First Mode docs.

1. Open the APIs module in Apidog.

2. Switch to Spec-First Mode.
   
   Use the mode toggle at the bottom-left of the APIs module and switch from Design-First to Spec-First Mode.

3. Connect your Git provider.
   
   Authorize GitHub or GitLab directly. For Azure DevOps, use a generic Git Connection with standard Git credentials.

4. Create a project from your repository.
   
   Select the repository that contains your OpenAPI spec.

5. Select the branch.
   
   Choose the target branch, typically main.

6. Configure team permissions.
   
   Decide who can access the project and what they can change.

7. Open the spec file.
   
   Edit openapi.yaml or openapi.json in the IDE-style editor.

8. Use validation and auto-completion.
   
   Fix OpenAPI errors as they appear and use suggestions while writing paths, schemas, parameters, and responses.

9. Review tracked changes.
   
   Confirm that only the intended files changed.

10. Commit the change.
    
    Write a clear commit message, such as:
    

    Add POST /invoices endpoint
    

11. Push to the repository.

12. Verify sync status.
    
    Confirm that the sync indicator shows the project is up to date.

The loop is straightforward:

pull -> edit -> validate -> review changes -> commit -> push -> verify sync

Example day-to-day workflow

A typical workflow looks like this:

1. Pull the latest changes from the connected branch.
2. Use the outline to jump to the operation or schema you need.
3. Edit the OpenAPI YAML or JSON.
4. Let validation catch malformed objects or broken $ref values.
5. Review file changes.
6. Commit with a clear message.
7. Push to Git.
8. Review the change through your normal pull request process.

For example, adding a schema might look like this:

components:
  schemas:
    Invoice:
      type: object
      required: [id, amount, currency]
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: integer
          description: Amount in the smallest currency unit
        currency:
          type: string
          example: USD
        status:
          type: string
          enum: [draft, sent, paid]

Because the spec lives in Git, teammates can review the API contract the same way they review application code.

Who should use Spec-First Mode?

Use Spec-First Mode if your team:

• Reviews API contracts in pull requests
• Versions OpenAPI files alongside service code
• Prefers editing YAML or JSON directly
• Uses Git as the source of truth
• Wants commit history for API contract changes
• Has backend or platform engineers owning API design

Choose Design-First Mode instead if your team wants:

• A guided visual editor
• Form-based API design
• Easier collaboration with non-engineers
• A lower learning curve for OpenAPI editing

Mixed teams often prefer Design-First Mode, while Git-native engineering teams usually benefit more from Spec-First Mode. For more detail, read the comparison post.

Limitations and beta notes

Spec-First Mode is currently in beta, so set expectations accordingly.

Important notes:

• Capabilities and behavior may change as the mode matures.
• GitHub and GitLab have direct integrations.
• Azure DevOps uses the generic Git Connection.
• You should confirm that your Git provider and workflow fit before using it for a critical project.
• Since the spec syncs with a live repository, normal Git discipline still applies.

A practical rollout approach:

1. Start with a non-critical repository.
2. Connect the spec.
3. Test a small edit-commit-push cycle.
4. Confirm your team can review and manage changes comfortably.
5. Expand usage once the workflow feels reliable.

The benefit of using a beta early is that feedback can influence the direction of the feature. If your workflow needs something specific, report it.

FAQ

Is Spec-First Mode free?

Spec-First Mode is a beta feature inside Apidog. Access depends on your Apidog plan and beta availability. The simplest way to check is to enable it in the APIs module and confirm whether it is available for your account.

Which Git providers are supported?

GitHub and GitLab are supported through direct integrations.

Azure DevOps works through a generic Git Connection using standard Git credentials. Other Git hosts may also work through the generic connection if they support standard Git access.

Can I switch back to Design-First Mode?

Yes. Use the mode toggle at the bottom-left of the APIs module to switch between Spec-First Mode and Design-First Mode.

You are not locked into one mode. Choose the mode that fits the project.

What file formats can I edit?

You can edit OpenAPI documents as raw YAML or JSON.

The editor provides syntax highlighting, schema validation, and auto-completion for OpenAPI and Swagger.

What happens to unpushed edits?

Unpushed edits stay local until you push them.

Spec-First Mode tracks changes as modified, added, or deleted. The sync indicator shows when work has not been pushed to the repository.

If you decide not to keep a change, discard it before pushing. It will not enter the shared Git history.

Conclusion

Apidog Spec-First Mode brings OpenAPI editing and Git sync into one workflow. You edit the spec as YAML or JSON, navigate it through an auto-parsed outline, validate it while writing, and sync changes with GitHub, GitLab, or Azure DevOps.

It is best suited for Git-native teams that want the OpenAPI document to behave like source code.

To try it safely:

1. Enable Spec-First Mode in the APIs module.
2. Connect a repository.
3. Open your OpenAPI file.
4. Make a small change.
5. Commit and push.
6. Confirm the sync status.

When you are ready, try Spec-First Mode in the docs and connect it to a repository you trust.