API Packages@mockmaster/openapi

@mockmaster/openapi

OpenAPI parsing & mock generation

npm install @mockmaster/openapi

Overview

The OpenAPI package enables parsing of OpenAPI 3.0 specifications and automatic generation of realistic mock data based on schemas.

Key Features:

  • Parse JSON and YAML OpenAPI specs
  • Generate mock data from schemas
  • Extract all operations from specs
  • Support for complex schemas and references
  • Format-aware data generation

API Reference

parseSpec(spec)

Parse a JSON OpenAPI specification.

import { parseSpec } from '@mockmaster/openapi'
 
const spec = parseSpec({
  openapi: '3.0.0',
  info: { title: 'My API', version: '1.0.0' },
  paths: {
    '/users': {
      get: {
        responses: {
          '200': {
            content: {
              'application/json': {
                schema: {
                  type: 'array',
                  items: {
                    type: 'object',
                    properties: {
                      id: { type: 'integer' },
                      name: { type: 'string' }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
})

Parameters:

  • spec (object) - JSON OpenAPI specification

Returns: Parsed OpenAPI spec object

parseYaml(yaml)

Parse a YAML OpenAPI specification.

import { parseYaml } from '@mockmaster/openapi'
 
const spec = parseYaml(`
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id: { type: integer }
                    name: { type: string }
`)

Parameters:

  • yaml (string) - YAML string

Returns: Parsed OpenAPI spec object

generateFromSchema(schema)

Generate mock data from a schema.

import { generateFromSchema } from '@mockmaster/openapi'
 
const schema = {
  type: 'object',
  properties: {
    id: { type: 'integer' },
    name: { type: 'string' },
    email: { type: 'string', format: 'email' }
  }
}
 
const data = generateFromSchema(schema)
// { id: 1, name: 'John Doe', email: 'john@example.com' }

Parameters:

  • schema (object) - JSON Schema or OpenAPI schema

Returns: Generated mock data

getAllOperations(spec)

Extract all operations from a spec.

import { getAllOperations } from '@mockmaster/openapi'
 
const operations = getAllOperations(spec)
 
operations.forEach(op => {
  console.log(`${op.method} ${op.path}`)
  console.log(`  operationId: ${op.operationId}`)
  console.log(`  summary: ${op.summary}`)
})

Parameters:

  • spec (object) - Parsed OpenAPI spec

Returns: Array of operation objects

Schema Support

Primitive Types

// String
{ type: 'string' }  // 'John Doe'
 
// Integer
{ type: 'integer' }  // 42
 
// Number
{ type: 'number' }  // 3.14
 
// Boolean
{ type: 'boolean' }  // true

String Formats

{ type: 'string', format: 'email' }       // 'john@example.com'
{ type: 'string', format: 'uri' }         // 'https://example.com'
{ type: 'string', format: 'date' }        // '2024-01-15'
{ type: 'string', format: 'date-time' }   // '2024-01-15T10:30:00Z'
{ type: 'string', format: 'uuid' }        // '123e4567-e89b...'
{ type: 'string', format: 'password' }    // 'xK9#mP2$...'

Number Constraints

{
  type: 'integer',
  minimum: 18,
  maximum: 80
}  // 42 (between 18 and 80)
 
{
  type: 'number',
  minimum: 0,
  maximum: 1
}  // 0.567 (between 0 and 1)

Arrays

{
  type: 'array',
  items: {
    type: 'string'
  }
}  // ['item1', 'item2', 'item3']
 
{
  type: 'array',
  items: {
    type: 'object',
    properties: {
      id: { type: 'integer' },
      name: { type: 'string' }
    }
  }
}  // [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]

Objects

{
  type: 'object',
  properties: {
    id: { type: 'integer' },
    name: { type: 'string' },
    email: { type: 'string', format: 'email' }
  },
  required: ['id', 'name']
}
// { id: 1, name: 'John Doe', email: 'john@example.com' }

Enums

{
  type: 'string',
  enum: ['active', 'inactive', 'pending']
}  // Randomly selects one: 'active'

References

const spec = {
  components: {
    schemas: {
      User: {
        type: 'object',
        properties: {
          id: { type: 'integer' },
          name: { type: 'string' }
        }
      }
    }
  },
  paths: {
    '/users/{id}': {
      get: {
        responses: {
          '200': {
            content: {
              'application/json': {
                schema: {
                  $ref: '#/components/schemas/User'
                }
              }
            }
          }
        }
      }
    }
  }
}
 
// MockMaster resolves references automatically

Usage Examples

Parse from File

import { readFileSync } from 'fs'
import { parseYaml, parseSpec } from '@mockmaster/openapi'
 
// YAML file
const yamlContent = readFileSync('./api-spec.yaml', 'utf-8')
const yamlSpec = parseYaml(yamlContent)
 
// JSON file
const jsonContent = readFileSync('./api-spec.json', 'utf-8')
const jsonSpec = parseSpec(JSON.parse(jsonContent))

Generate Data for Response

import { parseYaml, generateFromSchema } from '@mockmaster/openapi'
 
const spec = parseYaml(`
openapi: 3.0.0
paths:
  /users/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: integer }
                  name: { type: string }
                  email: { type: string, format: email }
`)
 
const operation = spec.paths['/users/{id}'].get
const schema = operation.responses['200'].content['application/json'].schema
 
const userData = generateFromSchema(schema)
console.log(userData)
// { id: 1, name: 'John Doe', email: 'john@example.com' }

List All Endpoints

import { parseYaml, getAllOperations } from '@mockmaster/openapi'
 
const spec = parseYaml(/* ... */)
const operations = getAllOperations(spec)
 
console.log('Available endpoints:')
operations.forEach(op => {
  console.log(`  ${op.method.toUpperCase()} ${op.path}`)
  if (op.summary) {
    console.log(`    ${op.summary}`)
  }
})

Complex Schema

const complexSchema = {
  type: 'object',
  properties: {
    user: {
      type: 'object',
      properties: {
        id: { type: 'integer' },
        profile: {
          type: 'object',
          properties: {
            firstName: { type: 'string' },
            lastName: { type: 'string' },
            avatar: { type: 'string', format: 'uri' }
          }
        },
        posts: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              id: { type: 'integer' },
              title: { type: 'string' },
              tags: {
                type: 'array',
                items: { type: 'string' }
              }
            }
          }
        }
      }
    },
    metadata: {
      type: 'object',
      properties: {
        timestamp: { type: 'string', format: 'date-time' },
        version: { type: 'string' }
      }
    }
  }
}
 
const data = generateFromSchema(complexSchema)
// Generates realistic nested data

Integration with CLI

The OpenAPI package works seamlessly with @mockmaster/cli:

import { parseYaml } from '@mockmaster/openapi'
import { generateScenariosFromSpec } from '@mockmaster/cli'
 
const spec = parseYaml(`
openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
`)
 
const scenarios = generateScenariosFromSpec(spec, 'user-api')
// Automatically generates scenarios with realistic data

TypeScript Types

import type {
  OpenAPISpec,
  SchemaObject,
  PathItemObject,
  OperationObject,
  ResponseObject
} from '@mockmaster/openapi'
 
// Use types for better IntelliSense
function processSpec(spec: OpenAPISpec) {
  // Type-safe access to spec properties
}
 
function generateFromSchema(schema: SchemaObject) {
  // Type-safe schema operations
}

Best Practices

1. Use Detailed Schemas

// Good - detailed constraints
{
  type: 'integer',
  minimum: 1,
  maximum: 100,
  description: 'User age'
}
 
// Basic - less realistic
{
  type: 'integer'
}

2. Leverage Formats

// Good - format-aware
{
  email: { type: 'string', format: 'email' },
  website: { type: 'string', format: 'uri' },
  birthDate: { type: 'string', format: 'date' }
}
 
// Avoid - generic
{
  email: { type: 'string' },
  website: { type: 'string' },
  birthDate: { type: 'string' }
}

3. Use References for Reusability

components:
  schemas:
    User:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
paths:
  /users:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
  /users/{id}:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

4. Document with Examples

components:
  schemas:
    User:
      type: object
      properties:
        status:
          type: string
          enum: ['active', 'inactive']
          example: 'active'

Related Documentation

@mockmaster/data@mockmaster/msw-adapter