DEV Community

Cover image for Spec-First or Design-First: Which Apidog Mode Should You Use?
Hassann
Hassann

Posted on • Originally published at apidog.com

Spec-First or Design-First: Which Apidog Mode Should You Use?

Apidog’s APIs module gives you two practical ways to author the same artifact: an API contract. Design-First Mode uses visual forms. Spec-First Mode uses a raw OpenAPI editor connected to Git. Both produce valid OpenAPI; the right default depends on how your team prefers to design, review, and version API changes.

Try Apidog today

This guide compares both workflows in Apidog, shows how Git fits into each mode, and gives you a practical decision path for choosing one. You can switch modes from a toggle in the bottom-left of the APIs module, so the choice is not permanent—but choosing the right default reduces day-to-day friction.

The two API design workflows

Both workflows start from the same principle: define the API contract before writing implementation code.

That contract becomes the source of truth for:

  • endpoint definitions
  • request and response schemas
  • examples
  • mocks
  • tests
  • documentation

The difference is how you author the contract.

Design-first

Design-first means you build the contract through a structured UI.

You define endpoints, parameters, schemas, and examples with forms, dropdowns, and schema editors. The tool generates the OpenAPI definition behind the scenes.

This is useful when you want contributors to focus on API structure without writing YAML or JSON manually.

Spec-first

Spec-first, often called contract-first, means you write the OpenAPI or Swagger file directly.

The spec itself is your editing surface. You work with it like source code, usually in YAML or JSON, and version it in Git.

In Apidog, the distinction is simple:

  • Design-First Mode = visual API designer
  • Spec-First Mode = OpenAPI/Swagger code editor with Git sync

This is separate from code-first API development. In code-first workflows, the spec is generated from implementation annotations. In both Apidog modes, the contract comes before the implementation.

For more background on treating the spec as a versioned artifact, see Apidog’s overview of the Git-native API workflow.

Apidog Design-First Mode

Design-First Mode is the visual API designer in Apidog.

You can use it to:

  1. Create an endpoint.
  2. Select an HTTP method.
  3. Define the path.
  4. Add path, query, header, or body parameters.
  5. Build request and response schemas with a tree editor.
  6. Attach examples.
  7. Generate the underlying OpenAPI contract automatically.

This mode works well when your team does not want to hand-write OpenAPI syntax.

For example, instead of manually writing a response schema like this:

components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
Enter fullscreen mode Exit fullscreen mode

You can define the same reusable Error schema through the schema editor.

Design-First Mode is useful when:

  • product managers need to review API behavior
  • QA engineers need to understand request and response shapes
  • junior developers need to contribute without deep OpenAPI knowledge
  • teams want faster API design without syntax errors
  • reviewers prefer structured diffs over raw YAML changes

It also supports branches, so teams can work on multiple API design versions in parallel and reconcile changes later.

The trade-off is that you are working through an abstraction. If your team already thinks in OpenAPI and wants direct file-level control, the visual editor may feel slower than editing the spec directly.

Apidog Spec-First Mode

Spec-First Mode, currently in beta, gives you an IDE-style editor for writing OpenAPI or Swagger directly in YAML or JSON.

Use this mode when you want your API definition to behave like any other source file in your repository.

The editor includes:

  • syntax highlighting
  • inline validation
  • OpenAPI/Swagger-aware auto-completion
  • an auto-parsed outline of paths and components
  • a sync indicator for Git status

A typical Spec-First workflow looks like this:

  1. Connect a GitHub, GitLab, or Azure DevOps repository.
  2. Select the OpenAPI or Swagger file to sync.
  3. Edit the spec in Apidog or in your code editor.
  4. Commit and push changes from Apidog, or push from your local Git workflow.
  5. Pull updates back into Apidog when the repository changes.

The key feature is two-way Git sync.

You can:

  • edit the spec in Apidog and push to Git
  • edit the spec locally and pull changes into Apidog
  • keep one canonical spec file shared across tools
  • review API changes in pull requests
  • version the API contract alongside service code

For setup details, see the Spec-First Mode docs.

This workflow fits teams that already manage configuration, infrastructure, and API definitions as code. For more on that approach, read Apidog’s article on API spec as code.

Side-by-side comparison

Both modes produce OpenAPI and support downstream workflows such as mocking, testing, and documentation. The main difference is how you author and version the contract.

Design-First Mode Spec-First Mode (beta)
Editor Visual forms and schema tree IDE-style YAML/JSON code editor
Spec format OpenAPI generated for you OpenAPI / Swagger written by hand
Git workflow Branch support inside Apidog Two-way sync with GitHub, GitLab, and Azure DevOps through Git Connection; commit and push from the app
Validation Enforced by form inputs Inline syntax validation and auto-completion
Navigation Endpoint list and folders Auto-parsed outline in the left sidebar
Learning curve Lower; OpenAPI knowledge is not required Higher; assumes OpenAPI fluency
Best for Mixed-skill teams and fast onboarding Engineering teams that treat the spec as code

How to choose the right mode

Use this decision path.

Choose Design-First Mode if:

  • not everyone on the team knows OpenAPI syntax
  • product, QA, or non-backend contributors need to review API changes
  • you are starting a new API from scratch
  • you want to move quickly through endpoint structure
  • you prefer UI-based schema editing
  • you want validation through guided inputs

Example use case:

A product manager, QA engineer, and backend developer need to agree on a new POST /orders endpoint. Design-First Mode lets them define the request body, response schema, and examples without editing YAML manually.

Choose Spec-First Mode if:

  • your OpenAPI file already lives in Git
  • your team reviews API changes through pull requests
  • you run spec linting or validation in CI
  • you want one canonical YAML or JSON file
  • backend engineers are comfortable editing OpenAPI directly
  • the API contract should sit next to service code

Example use case:

A backend team maintains openapi.yaml in the same repository as the service implementation. API changes are reviewed in pull requests, validated in CI, and synced into Apidog for documentation, testing, and mocks.

A practical hybrid workflow

You do not have to treat the modes as competing options.

A common workflow is:

  1. Start in Design-First Mode to draft endpoints quickly.
  2. Review schemas and examples with product, QA, and engineering.
  3. Switch to Spec-First Mode when the API stabilizes.
  4. Connect the spec to Git.
  5. Review future API changes through pull requests.

This lets teams use the visual designer for speed and the Git-connected editor for long-term governance.

The contract stays the same. Only the editing surface changes.

How to switch modes in Apidog

Switching modes takes one action.

  1. Open your Apidog project.
  2. Go to the APIs module.
  3. Find the mode switcher in the bottom-left corner.
  4. Toggle between Design-First Mode and Spec-First Mode.

When you switch:

  • endpoints remain available
  • schemas carry across
  • examples stay attached
  • the underlying contract is shared
  • you are changing the editor, not rebuilding the API

If you want to use Spec-First Mode’s Git sync, connect your repository first. Apidog supports GitHub and GitLab directly, while Azure DevOps works through a generic Git Connection.

Because Spec-First Mode is currently in beta, test the sync behavior on a safe project before depending on it for a production API contract.

FAQ

Is spec-first the same as contract-first?

In practice, yes.

Both terms mean you define the API specification before writing the implementation. The spec is the source of truth.

In Apidog, Spec-First Mode is a contract-first workflow where the contract is a hand-written OpenAPI or Swagger file synced with Git.

Does Spec-First Mode work with GitLab and Azure DevOps?

Yes.

Spec-First Mode supports two-way Git sync with GitHub and GitLab. Azure DevOps works through a generic Git Connection, so you can sync a spec file from an Azure-hosted repository.

Can I switch from Design-First Mode to Spec-First Mode without losing work?

Yes.

Both modes read and write the same underlying contract. Your endpoints, schemas, and examples stay intact when you use the toggle in the bottom-left of the APIs module.

You are changing the editor, not the API data.

Final recommendation

Pick the mode that matches how your team already works.

Use Design-First Mode when you need speed, accessibility, and visual editing.

Use Spec-First Mode when Git, pull requests, and direct OpenAPI editing are central to your workflow.

If you are unsure, design the same endpoint once in each mode. The contract is the same either way; the better choice is the editing surface your team will actually use.

Top comments (0)