API Development With Apidog: Design-First Workflow, Mocks and CI Tests

Apidog is an API platform that combines design, debugging, testing, mocking and documentation in one tool, in the same space as Postman, Insomnia and Stoplight. This guide walks through a design-first workflow with Apidog: describe the API in OpenAPI, import it, mock it so front-end work can start, test it, and run those tests in CI with the Apidog CLI.

What I checked for this update: the OpenAPI file below validates with Redocly CLI 2.67, the GitHub Actions workflow passes actionlint, and the Apidog CLI (version 2.2.12) commands and flags are taken from its own --help output. Running test scenarios needs an Apidog account and access token, which I did not use, so the CI run itself is not demonstrated. Feature details come from Apidog’s documentation. The 2024 version of this post was a feature tour with several GUI steps I could not match to the current product, so those are replaced with steps from the docs.

What Apidog Covers

On pricing, the docs say billing is per member, that documentation readers are not charged, and that the free plan supports up to four users. Check Apidog’s pricing page for current plan prices.

Step 1: Design the API First

Design-first means agreeing on the contract before writing server code: the front-end, back-end and QA teams all work from the same definition, and mocks and tests come from it for free. You can design endpoints in Apidog’s editor, but keeping an OpenAPI file in your repository has an advantage: it is reviewed in pull requests like code and is not tied to one tool. Here is a small Orders API in OpenAPI 3.1:

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
  description: Design-first example for importing into Apidog.
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://api.example.com/v1
security:
  - bearerAuth: []
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      parameters:
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/OrderStatus'
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: A page of orders
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Order' }
                  nextCursor: { type: [string, 'null'] }
        '401': { $ref: '#/components/responses/Problem' }
    post:
      operationId: createOrder
      summary: Create an order
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/NewOrder' }
      responses:
        '201':
          description: Created
          headers:
            Location:
              schema: { type: string }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '401': { $ref: '#/components/responses/Problem' }
        '422': { $ref: '#/components/responses/Problem' }
  /orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get an order
      parameters:
        - name: orderId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The order
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Order' }
        '401': { $ref: '#/components/responses/Problem' }
        '404': { $ref: '#/components/responses/Problem' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  responses:
    Problem:
      description: Error in RFC 9457 problem details format
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              title: { type: string }
              status: { type: integer }
              detail: { type: string }
  schemas:
    OrderStatus:
      type: string
      enum: [pending, paid, shipped, cancelled]
    NewOrder:
      type: object
      required: [customerEmail, items]
      properties:
        customerEmail: { type: string, format: email, examples: [[email protected]] }
        items:
          type: array
          minItems: 1
          items:
            type: object
            required: [sku, quantity]
            properties:
              sku: { type: string, examples: [MUG-BLUE] }
              quantity: { type: integer, minimum: 1, maximum: 99 }
    Order:
      allOf:
        - $ref: '#/components/schemas/NewOrder'
        - type: object
          required: [id, status, createdAt]
          properties:
            id: { type: string, examples: [ord_123] }
            status: { $ref: '#/components/schemas/OrderStatus' }
            createdAt: { type: string, format: date-time }

Validate it before importing. Redocly CLI reported it valid, with one warning that the server URL uses example.com:

$ npx @redocly/cli lint openapi.yaml
openapi.yaml: validated in 57ms
Woohoo! Your API description is valid. 🎉
You have 1 warning.

A few design choices in the file worth copying: reusable schemas under components, one error format (application/problem+json) shared by every endpoint, explicit limits (minimum, maximum, minItems), and examples on fields. Smart Mock uses all of these.

Step 2: Import It Into Apidog

Create a project in Apidog and import the file from the app, or use the CLI, whose import command accepts OpenAPI along with Postman, Insomnia, HAR and many other formats:

npm install -g apidog-cli
apidog auth --help        # sign in
apidog import --project <projectId> --format openapi --file ./openapi.yaml

The import command’s --overwrite-mode option (overwrite, merge, ignore or keepBoth) controls what happens to endpoints that already exist, so you can re-import after every change to the spec.

Step 3: Mock the API

Mocks let front-end and mobile developers build against the API before it exists. According to the docs, Smart Mock “automatically generates realistic API responses based on your API specifications without requiring additional configuration”, respecting constraints such as string lengths, enums, number ranges and array sizes. For a URL that works without your machine running, enable Cloud Mock under Project Settings, Mock Settings; it can be protected with a token.

This is where a detailed schema pays off: the enum on status and the minimum and maximum on quantity produce realistic mock data instead of random strings.

Step 4: Debug and Test

• Environments: define local, staging and production base URLs and secrets as environment variables, so the same requests run anywhere.
• Test cases: check status codes, response schemas and specific values for single endpoints, including error cases such as 401, 404 and 422.
• Test scenarios: chain requests into flows such as “create an order, then fetch it, then cancel it”, passing values like IDs between steps.
• Data-driven runs: feed CSV or JSON data to run the same scenario with many inputs.

Test the unhappy paths as carefully as the happy ones: invalid input, missing auth, unknown IDs and rate limits are where APIs usually break.

Step 5: Run Tests in CI

The Apidog CLI runs test scenarios outside the app. Its run command takes an access token with -t for a scenario (or -f for a folder), -e for an environment, and -r for report formats including cli, html, json and junit. In the app, the CI/CD tab of a test scenario generates the command for your platform. A GitHub Actions job:

name: API tests

on:
  pull_request:
  push:
    branches: [main]

jobs:
  apidog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - name: Install Apidog CLI
        run: npm install -g apidog-cli
      - name: Run Apidog test scenario against staging
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
        run: >
          apidog run
          --access-token "$APIDOG_ACCESS_TOKEN"
          -t ${{ vars.APIDOG_SCENARIO_ID }}
          -e ${{ vars.APIDOG_STAGING_ENV_ID }}
          -r cli,junit
          --out-dir apidog-reports
      - name: Upload test report
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: apidog-reports
          path: apidog-reports

Store the access token as a repository secret and the scenario and environment IDs as repository variables. The JUnit report lets most CI systems show test results inline. For EU-region workspaces, the docs say to add --api-base-url https://api.eu.apidog.com.

How Each Role Uses It

Apidog or Something Else?

Apidog suits teams that want design, mocks, tests and docs in one place. If your team already relies on Postman collections, the switching cost may not be worth it; if you prefer everything in code, tools like an OpenAPI linter plus a code-based test framework (for example supertest in Node.js) work without a separate platform. Whatever you choose, keep the OpenAPI file in version control so you are not locked in. For building the API itself, see REST APIs with Node.js and Express.

Conclusion

A good Apidog workflow starts from a well-described OpenAPI contract: import it, let mocks unblock client teams, build test scenarios around real and failure cases, and run them on every pull request with the CLI. The contract stays the single source of truth for code, tests and documentation. For calling APIs from client code, see how to make an HTTP request.

FAQs