What is OpenAPI?

OpenAPI (formerly Swagger) is an industry-standard specification format for describing RESTful APIs. It defines endpoints, request/response schemas, authentication, and more in a structured JSON or YAML format.

Benefits of OpenAPI Import

Instant Setup: Create complete APIs in seconds, not hours
Accurate Structure: Preserve exact data types and validation rules
Team Collaboration: Share specs between backend and frontend teams
Documentation: Import descriptions and examples automatically
Consistency: Ensure mock API matches production spec

Supported Formats

OpenAPI 3.x (JSON)

Modern OpenAPI format in JSON

json

Recommended

OpenAPI 3.x (YAML)

Modern OpenAPI format in YAML

yaml

Recommended

Swagger 2.0 (JSON)

Legacy Swagger format

json

Supported

Swagger 2.0 (YAML)

Legacy Swagger format

yaml

Supported

How to Import

Navigate to Import Page

Go to Dashboard → Import or click the "Import" button in the navigation

Choose Import Method

Select one of three convenient import methods:

From File (Recommended)

New!

Upload your OpenAPI specification file with drag-and-drop support

Features:

Drag and drop files directly into the upload zone
Browse and select files from your computer
Supports .json, .yaml, and .yml file extensions
Real-time file preview before importing

Security Features:

File extension validation (.json, .yaml, .yml only)
Maximum file size: 5MB
MIME type verification
Content sanitization to prevent malicious code
JSON/YAML parsing validation before processing

From URL

Import directly from a publicly accessible URL

Perfect for importing from:

GitHub repositories (raw file URLs)
Public API documentation sites
Swagger/OpenAPI hosting services
Your own hosted specification files

Example: https://petstore.swagger.io/v2/swagger.json

Paste JSON/YAML

Copy and paste your specification content directly

Features:

• Monaco code editor with syntax highlighting
• Auto-detects JSON or YAML format
• Built-in format/prettify button
• Supports both OpenAPI 3.x and Swagger 2.0

Preview & Validate

Click "Preview" to validate and see what will be imported

Valid OpenAPI 3.0.0 specification detected

The preview shows:

• Number of endpoints that will be created
• Data schemas and models
• HTTP methods for each path
• Interactive endpoint testing

Configure Project Settings

Customize your import:

• Set a custom project name (or use the API title)
• Enable/disable Faker.js for realistic mock data
• Review the base URL and description

Import Complete!

Your project is created with all endpoints and schemas ready to use. You'll be automatically redirected to your new project dashboard.

What Gets Imported?

🔑 Important: Endpoint Splitting Behavior

Mock API Builder stores each HTTP method as a separate endpoint record. When importing an OpenAPI spec, paths with multiple operations are automatically split:

Example OpenAPI Spec:

yaml

Results in 5 separate database records:

1. GET /users

2. POST /users

3. GET /users/:id

4. PUT /users/:id

5. DELETE /users/:id

Each endpoint can be independently configured, tested, or deleted after import. This design allows fine-grained control over each operation's schema, validation rules, and mock data.

Endpoints & Paths

All paths from the spec become API endpoints (split by HTTP method):

/users → 2 endpoints (GET, POST)/users/{id} → 3 endpoints (GET, PUT, DELETE)/products → 2 endpoints (GET, POST)

Total endpoints created = sum of all HTTP methods across all paths

Data Schemas

Schema definitions are converted to database models:

OpenAPI:

type: string

Mock API:

String field

type: integer

Number field

HTTP Methods (Split into Separate Endpoints)

Each HTTP method becomes its own endpoint record:

• GET operations → Independent GET endpoints
• POST operations → Independent POST endpoints
• PUT/PATCH operations → Independent UPDATE endpoints
• DELETE operations → Independent DELETE endpoints

Descriptions & Examples

Field descriptions and example values from the spec are preserved

Validation Rules

Constraints are automatically applied:

• Required fields
• String length (minLength, maxLength)
• Number ranges (minimum, maximum)
• Enum values
• Pattern matching (regex)

External API URL Transformation

When importing OpenAPI specs from external APIs, Mock API Builder automatically transforms the base URL to work with our proxy system. This enables powerful features like proxy mode and hybrid testing.

How URL Transformation Works

External URLs are converted to our internal routing format

Original URL (from your OpenAPI spec):

https://petstore.swagger.io/v2

Transformed URL (used in Mock API Builder):

/api/petstore.swagger.io/v2

The original URL is stored in your project settings, enabling proxy mode to forward requests to the real API when needed.

What Gets Transformed

• https://api.example.com/v1 → /api/api.example.com/v1
• http://localhost:3001 → /api/localhost:3001
• https://petstore.swagger.io/v2 → /api/petstore.swagger.io/v2

Protocol Detection

• External URLs default to HTTPS
• localhost, 127.0.0.1, 0.0.0.0 use HTTP
• Original protocol preserved in settings

Import Notification

When you import an OpenAPI spec with an external URL, you'll see a notification showing the URL transformation. This confirms that proxy mode will be available for your project.

Proxy Mode

After importing an OpenAPI spec from an external API, you can switch between three powerful modes to control how your endpoints respond.

Mock Mode

Default

Returns generated mock data based on your endpoint configurations and response templates.

Best for:

• Frontend development
• Offline testing
• Controlled test scenarios

Proxy Mode

Live Data

Forwards all requests to the original external API and returns real responses.

Best for:

• Integration testing
• Production debugging
• Real data validation

Hybrid Mode

Advanced

Uses mock data when available, falls back to the real API for unconfigured endpoints.

Best for:

• Partial API mocking
• Gradual migration
• Mixed testing scenarios

How to Change Proxy Mode

1Open your project in the dashboard
2Click the Settings button (gear icon)
3In the "Proxy Mode" section, select Mock, Proxy, or Hybrid
4Click Save Changes to apply

Note: Proxy mode settings are only available for projects imported from external OpenAPI specs.

Example OpenAPI Spec

Complete User API Example

json

This creates 3 endpoints with full CRUD operations

Mock Data Generation

After importing, you can automatically generate mock data based on your schemas:

Automatic Field Mapping

Field types are intelligently mapped to Faker.js generators:

format: email

→ faker.internet.email()

format: date-time

→ faker.date.recent()

format: uri

→ faker.internet.url()

type: boolean

→ faker.datatype.boolean()

Example Values

If your spec includes example values, they're used as templates:

json

File Upload Tips

Get the most out of the file upload feature with these helpful tips:

Drag and Drop

Simply drag your OpenAPI specification file from your file explorer and drop it into the upload zone. The zone will highlight when a file is being dragged over it.

Tip: You can drag files directly from GitHub, your IDE, or any file manager.

File Size Limits

Maximum file size is 5MB. This is sufficient for most OpenAPI specifications.

If your spec exceeds this limit, consider:

• Splitting it into smaller specs by feature/module
• Removing unnecessary examples or descriptions
• Using the URL import method instead

Supported File Types

Accepted file extensions:

.json

.yaml

.yml

Files with other extensions will be rejected for security reasons.

File Preview

After uploading, you'll see a preview of your file's content in the code editor. You can review and even edit the content before clicking "Preview" to validate the specification.

Security & Privacy

Your uploaded files are:

✓ Validated for file type and size
✓ Sanitized to remove potentially malicious content
✓ Parsed and validated before processing
✓ Not stored on the server (only the parsed project data is saved)

Common Issues & Solutions

File Upload Rejected

Problem: "Invalid file type" or "File size exceeds limit"

Solutions:

• Ensure file has .json, .yaml, or .yml extension
• Check file size is under 5MB
• Verify the file isn't corrupted
• Try using the "Paste JSON/YAML" method instead

Invalid Spec Format

Problem: "Invalid OpenAPI specification"

Solutions:

• Validate your spec at editor.swagger.io
• Check JSON/YAML syntax for errors
• Ensure openapi version is specified correctly
• Verify all $ref references are valid

Missing Schemas

Problem: Endpoints imported but no data structure

Solution: Define schemas in components/schemas section

Large Spec Files

Problem: Import takes a long time or times out

Solution: Split large specs into smaller ones or import only needed paths

Best Practices

✓ Validate Before Import

Use Swagger Editor or online validators to ensure your spec is valid before importing.

✓ Include Examples

Add example values to your schemas for better mock data generation.

✓ Use Components/Schemas

Define reusable schemas in components section to avoid duplication and ensure consistency.

✓ Keep Specs Updated

When your backend API changes, re-import the updated spec to keep your mock API in sync.

What is OpenAPI?

Benefits of OpenAPI Import

Instant Setup: Create complete APIs in seconds, not hours
Accurate Structure: Preserve exact data types and validation rules
Team Collaboration: Share specs between backend and frontend teams
Documentation: Import descriptions and examples automatically
Consistency: Ensure mock API matches production spec

Supported Formats

OpenAPI 3.x (JSON)

Modern OpenAPI format in JSON

json

Recommended

OpenAPI 3.x (YAML)

Modern OpenAPI format in YAML

yaml

Recommended

Swagger 2.0 (JSON)

Legacy Swagger format

json

Supported

Swagger 2.0 (YAML)

Legacy Swagger format

yaml

Supported

How to Import

Navigate to Import Page

Go to Dashboard → Import or click the "Import" button in the navigation

Choose Import Method

Select one of three convenient import methods:

From File (Recommended)

New!

Upload your OpenAPI specification file with drag-and-drop support

Features:

Drag and drop files directly into the upload zone
Browse and select files from your computer
Supports .json, .yaml, and .yml file extensions
Real-time file preview before importing

Security Features:

File extension validation (.json, .yaml, .yml only)
Maximum file size: 5MB
MIME type verification
Content sanitization to prevent malicious code
JSON/YAML parsing validation before processing

From URL

Import directly from a publicly accessible URL

Perfect for importing from:

GitHub repositories (raw file URLs)
Public API documentation sites
Swagger/OpenAPI hosting services
Your own hosted specification files

Example: https://petstore.swagger.io/v2/swagger.json

Paste JSON/YAML

Copy and paste your specification content directly

Features:

• Monaco code editor with syntax highlighting
• Auto-detects JSON or YAML format
• Built-in format/prettify button
• Supports both OpenAPI 3.x and Swagger 2.0

Preview & Validate

Click "Preview" to validate and see what will be imported

Valid OpenAPI 3.0.0 specification detected

The preview shows:

• Number of endpoints that will be created
• Data schemas and models
• HTTP methods for each path
• Interactive endpoint testing

Configure Project Settings

Customize your import:

• Set a custom project name (or use the API title)
• Enable/disable Faker.js for realistic mock data
• Review the base URL and description

Import Complete!

Your project is created with all endpoints and schemas ready to use. You'll be automatically redirected to your new project dashboard.

What Gets Imported?

🔑 Important: Endpoint Splitting Behavior

Mock API Builder stores each HTTP method as a separate endpoint record. When importing an OpenAPI spec, paths with multiple operations are automatically split:

Example OpenAPI Spec:

yaml

Results in 5 separate database records:

1. GET /users

2. POST /users

3. GET /users/:id

4. PUT /users/:id

5. DELETE /users/:id

Each endpoint can be independently configured, tested, or deleted after import. This design allows fine-grained control over each operation's schema, validation rules, and mock data.

Endpoints & Paths

All paths from the spec become API endpoints (split by HTTP method):

/users → 2 endpoints (GET, POST)/users/{id} → 3 endpoints (GET, PUT, DELETE)/products → 2 endpoints (GET, POST)

Total endpoints created = sum of all HTTP methods across all paths

Data Schemas

Schema definitions are converted to database models:

OpenAPI:

type: string

Mock API:

String field

type: integer

Number field

HTTP Methods (Split into Separate Endpoints)

Each HTTP method becomes its own endpoint record:

• GET operations → Independent GET endpoints
• POST operations → Independent POST endpoints
• PUT/PATCH operations → Independent UPDATE endpoints
• DELETE operations → Independent DELETE endpoints

Descriptions & Examples

Field descriptions and example values from the spec are preserved

Validation Rules

Constraints are automatically applied:

• Required fields
• String length (minLength, maxLength)
• Number ranges (minimum, maximum)
• Enum values
• Pattern matching (regex)

External API URL Transformation

How URL Transformation Works

External URLs are converted to our internal routing format

Original URL (from your OpenAPI spec):

https://petstore.swagger.io/v2

Transformed URL (used in Mock API Builder):

/api/petstore.swagger.io/v2

The original URL is stored in your project settings, enabling proxy mode to forward requests to the real API when needed.

What Gets Transformed

• https://api.example.com/v1 → /api/api.example.com/v1
• http://localhost:3001 → /api/localhost:3001
• https://petstore.swagger.io/v2 → /api/petstore.swagger.io/v2

Protocol Detection

• External URLs default to HTTPS
• localhost, 127.0.0.1, 0.0.0.0 use HTTP
• Original protocol preserved in settings

Import Notification

When you import an OpenAPI spec with an external URL, you'll see a notification showing the URL transformation. This confirms that proxy mode will be available for your project.

Proxy Mode

After importing an OpenAPI spec from an external API, you can switch between three powerful modes to control how your endpoints respond.

Mock Mode

Default

Returns generated mock data based on your endpoint configurations and response templates.

Best for:

• Frontend development
• Offline testing
• Controlled test scenarios

Proxy Mode

Live Data

Forwards all requests to the original external API and returns real responses.

Best for:

• Integration testing
• Production debugging
• Real data validation

Hybrid Mode

Advanced

Uses mock data when available, falls back to the real API for unconfigured endpoints.

Best for:

• Partial API mocking
• Gradual migration
• Mixed testing scenarios

How to Change Proxy Mode

1Open your project in the dashboard
2Click the Settings button (gear icon)
3In the "Proxy Mode" section, select Mock, Proxy, or Hybrid
4Click Save Changes to apply

Note: Proxy mode settings are only available for projects imported from external OpenAPI specs.

Example OpenAPI Spec

Complete User API Example

json

This creates 3 endpoints with full CRUD operations

Mock Data Generation

After importing, you can automatically generate mock data based on your schemas:

Automatic Field Mapping

Field types are intelligently mapped to Faker.js generators:

format: email

→ faker.internet.email()

format: date-time

→ faker.date.recent()

format: uri

→ faker.internet.url()

type: boolean

→ faker.datatype.boolean()

Example Values

If your spec includes example values, they're used as templates:

json

File Upload Tips

Get the most out of the file upload feature with these helpful tips:

Drag and Drop

Simply drag your OpenAPI specification file from your file explorer and drop it into the upload zone. The zone will highlight when a file is being dragged over it.

Tip: You can drag files directly from GitHub, your IDE, or any file manager.

File Size Limits

Maximum file size is 5MB. This is sufficient for most OpenAPI specifications.

If your spec exceeds this limit, consider:

• Splitting it into smaller specs by feature/module
• Removing unnecessary examples or descriptions
• Using the URL import method instead

Supported File Types

Accepted file extensions:

.json

.yaml

.yml

Files with other extensions will be rejected for security reasons.

File Preview

After uploading, you'll see a preview of your file's content in the code editor. You can review and even edit the content before clicking "Preview" to validate the specification.

Security & Privacy

Your uploaded files are:

✓ Validated for file type and size
✓ Sanitized to remove potentially malicious content
✓ Parsed and validated before processing
✓ Not stored on the server (only the parsed project data is saved)

Common Issues & Solutions

File Upload Rejected

Problem: "Invalid file type" or "File size exceeds limit"

Solutions:

• Ensure file has .json, .yaml, or .yml extension
• Check file size is under 5MB
• Verify the file isn't corrupted
• Try using the "Paste JSON/YAML" method instead

Invalid Spec Format

Problem: "Invalid OpenAPI specification"

Solutions:

• Validate your spec at editor.swagger.io
• Check JSON/YAML syntax for errors
• Ensure openapi version is specified correctly
• Verify all $ref references are valid

Missing Schemas

Problem: Endpoints imported but no data structure

Solution: Define schemas in components/schemas section

Large Spec Files

Problem: Import takes a long time or times out

Solution: Split large specs into smaller ones or import only needed paths

Best Practices

✓ Validate Before Import

Use Swagger Editor or online validators to ensure your spec is valid before importing.

✓ Include Examples

Add example values to your schemas for better mock data generation.

✓ Use Components/Schemas

Define reusable schemas in components section to avoid duplication and ensure consistency.

✓ Keep Specs Updated

When your backend API changes, re-import the updated spec to keep your mock API in sync.