openapi-sampler

What is openapi-sampler?

The openapi-sampler npm package is used to generate sample data from OpenAPI specifications. It helps in creating mock data for API responses based on the defined schemas in the OpenAPI document.

What are openapi-sampler's main functionalities?

Generate Sample from Schema

This feature allows you to generate a sample object based on a given JSON schema. The sample data will adhere to the types and examples specified in the schema.

const openapiSampler = require('openapi-sampler');
const schema = {
  type: 'object',
  properties: {
    id: { type: 'integer', example: 1 },
    name: { type: 'string', example: 'John Doe' }
  }
};
const sample = openapiSampler.sample(schema);
console.log(sample);

Generate Sample from OpenAPI Document

This feature allows you to generate sample data directly from an OpenAPI document. It extracts the schema from the specified path and response, and generates a sample based on it.

const openapiSampler = require('openapi-sampler');
const openapiDoc = {
  openapi: '3.0.0',
  info: { title: 'Sample API', version: '1.0.0' },
  paths: {
    '/user': {
      get: {
        responses: {
          '200': {
            description: 'A user object',
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  properties: {
                    id: { type: 'integer', example: 1 },
                    name: { type: 'string', example: 'John Doe' }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
};
const sample = openapiSampler.sample(openapiDoc.paths['/user'].get.responses['200'].content['application/json'].schema);
console.log(sample);

Other packages similar to openapi-sampler

swagger-mock-api

The swagger-mock-api package is used to create a mock server based on Swagger (OpenAPI) definitions. It allows you to simulate API endpoints and responses for testing purposes. Unlike openapi-sampler, which focuses on generating sample data, swagger-mock-api provides a full mock server implementation.

swagger-jsdoc

The swagger-jsdoc package is used to generate Swagger (OpenAPI) documentation from JSDoc comments in your code. While it does not generate sample data, it helps in creating and maintaining OpenAPI documentation, which can then be used with tools like openapi-sampler to generate sample data.

json-schema-faker

The json-schema-faker package generates fake data based on JSON Schema definitions. It is similar to openapi-sampler in that it generates sample data, but it is more focused on JSON Schema rather than OpenAPI specifically. It offers more customization options for generating fake data.

README

openapi-sampler

Tool for generation samples based on OpenAPI payload/response schema

Features

• Deterministic (given a particular input, will always produce the same output)
• Supports compound keywords: allOf, oneOf, anyOf, if/then/else
• Supports additionalProperties with x-additionalPropertiesName
• Uses const, examples, enum and default where possible - in this order
• Good array support: supports contains, minItems, maxItems, and tuples (items as an array)
• Supports minLength, maxLength, min, max, exclusiveMinimum, exclusiveMaximum
• Supports the following string formats:
  • email
  • idn-email
  • password
  • date-time
  • date
  • time
  • ipv4
  • ipv6
  • hostname
  • idn-hostname
  • uri
  • uri-reference
  • uri-template
  • iri
  • iri-reference
  • uuid
  • json-pointer
  • relative-json-pointer
  • regex
• Infers schema type automatically following same rules as json-schema-faker
• Support for $ref resolving
• Has basic supports for JSON Schema draft 7 (thanks to @P0lip from @stoplightio for contributing)

Installation

Install using npm

npm install openapi-sampler --save

or using yarn

yarn add openapi-sampler

Then require it in your code:

var OpenAPISampler = require('openapi-sampler');

Usage

OpenAPISampler.sample(schema, [options], [spec])

• schema (required) - object An OpenAPI Schema Object or a JSON Schema Draft 7 document.
• options (optional) - object Available options:
  • skipNonRequired - boolean Don't include non-required object properties not specified in required property of the schema object
  • skipReadOnly - boolean Don't include readOnly object properties
  • skipWriteOnly - boolean Don't include writeOnly object properties
  • quiet - boolean Don't log console warning messages
• spec - whole specification where the schema is taken from. Required only when schema may contain $ref. spec must not contain any external references

Example

const OpenAPISampler = require('.');
OpenAPISampler.sample({
  type: 'object',
  properties: {
    a: {type: 'integer', minimum: 10},
    b: {type: 'string', format: 'password', minLength: 10},
    c: {type: 'boolean', readOnly: true}
  }
}, {skipReadOnly: true});
// { a: 10, b: 'pa$$word_q' }