Skip to documentation

Workspace · OpenAPI

Available

Start from the contract you already have

Import an OpenAPI or Swagger document to create the REST surface quickly, then review the generated models and add the state, failures, and sequences your client actually needs to exercise.

In this guide

  • Create endpoints from an existing contract
  • Preserve reusable schemas and operation metadata
  • Find unsupported or ambiguous input early
  • Turn static examples into testable behavior

Prerequisites

  • A valid OpenAPI or Swagger document
  • Permission to create an API in the target team
On this page
  1. Use a complete, valid source document
  2. Create the workspace from OpenAPI
  3. Review the contract before adding behavior
  4. Prove the important journeys

Use a complete, valid source document

Prefer a resolved OpenAPI 3 document with operation IDs, reusable component schemas, explicit request and response content types, and representative examples. Swagger 2 definitions can be imported, but modern content and schema detail produces a better starting point.

yaml
openapi: 3.2.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      operationId: getUser
      responses:
        '200':
          description: User found

Create the workspace from OpenAPI

Choose New workspace, select REST API, then import the document by file or pasted source. DotMock validates the document before creating the workspace and reports actionable issues instead of silently dropping invalid operations.

  • Paths and HTTP methods become endpoints
  • Path, query, and header parameters remain request inputs
  • Component schemas become reusable models
  • Request bodies and response schemas remain attached to their operations
  • Examples seed useful default tester and response values when available

Review the contract before adding behavior

Check every path parameter, required field, content type, status code, and schema reference. Imported examples are contract examples, not persistent behavior; choose which operations need conditions, state, faults, proxying, or hooks.

Prove the important journeys

Use the generated request examples to dry-run success and error responses. For related operations, add a shared model and state resource, then test create → read → update → missing. Publish only after the tester shows the intended winner and response contract.

bash
dotmock --json test --api "$API_ID" --method GET --path /users/usr_123