# openapi-sampler

> Tool for generation samples based on OpenAPI payload/response schema

Latest version **1.7.6** (published 2026-09-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install openapi-sampler
pnpm add openapi-sampler
yarn add openapi-sampler
bun add openapi-sampler
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.7.6 |
| Published | 2026-09-16 |
| First published | 2016-05-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 157.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 227 |
| Author | Roman Hotsiy |
| Maintainers | romanhotsiy |
| Keywords | OpenAPI, Swagger, instantiator, sampler, faker |

## Links

- npm: https://www.npmjs.com/package/openapi-sampler
- Repository: https://github.com/Redocly/openapi-sampler
- Homepage: https://github.com/Redocly/openapi-sampler/
- Issues: https://github.com/Redocly/openapi-sampler/issues
- npm.io page: https://npm.io/package/openapi-sampler

## Dependencies (3)

- [json-pointer](https://npm.io/package/json-pointer.md) 0.6.2
- [fast-xml-parser](https://npm.io/package/fast-xml-parser.md) ^5.5.1
- [@types/json-schema](https://npm.io/package/@types/json-schema.md) ^7.0.7

## Alternatives

- [pagerjs](https://npm.io/package/pagerjs.md) — 60 weekly downloads
- [whistle.savefor-mock](https://npm.io/package/whistle.savefor-mock.md) — 4 weekly downloads
- [@noahbleau/winfio](https://npm.io/package/@noahbleau/winfio.md) — 0 weekly downloads
- [@nocville/node](https://npm.io/package/@nocville/node.md) — 0 weekly downloads
- [@webda/mock](https://npm.io/package/@webda/mock.md) — 0 weekly downloads

## Recent versions

- 1.7.6 (latest) — 2026-09-16
- 1.7.5 — 2026-09-03
- 1.7.4 — 2026-05-27
- 1.7.3 — 2026-05-07
- 1.7.2 — 2026-03-10
- 1.7.1 — 2026-03-02
- 1.7.0 — 2026-02-16
- 1.6.2 — 2025-10-14
- 1.6.1 — 2024-11-30
- 1.6.0 — 2024-11-20
- 1.5.1 — 2024-05-02
- 1.5.0 — 2024-04-24
- 1.4.0 — 2023-12-04
- 1.3.1 — 2023-01-11
- 1.3.0 — 2022-05-30
- … 42 more at https://npm.io/package/openapi-sampler/versions

## README

# openapi-sampler

[![Travis build status](http://img.shields.io/travis/Redocly/openapi-sampler.svg?style=flat)](https://travis-ci.org/Redocly/openapi-sampler) [![Coverage Status](https://coveralls.io/repos/Redocly/openapi-sampler/badge.svg?branch=master&service=github)](https://coveralls.io/github/Redocly/openapi-sampler?branch=master) [![Dependency Status](https://david-dm.org/Redocly/openapi-sampler.svg)](https://david-dm.org/Redocly/openapi-sampler) [![devDependency Status](https://david-dm.org/Redocly/openapi-sampler/dev-status.svg)](https://david-dm.org/Redocly/openapi-sampler#info=devDependencies)

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`](https://github.com/Redocly/redoc/blob/master/docs/redoc-vendor-extensions.md#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`, ([limited](https://fakerjs.dev/api/helpers.html#fromregexp)) `pattern`
- 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](https://www.npmjs.com/package/json-schema-faker#inferred-types)
- Support for `$ref` resolving
- Has basic supports for JSON Schema draft 7 (thanks to [@P0lip](https://github.com/P0lip) from [@stoplightio](https://github.com/stoplightio) for contributing)

## Installation

Install using [npm](https://docs.npmjs.com/getting-started/what-is-npm)

    npm install openapi-sampler

or using [yarn](https://yarnpkg.com)

    yarn add openapi-sampler

Then require it in your code:

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

## Usage
#### `OpenAPISampler.sample(schema, [options], [spec])`
- **schema** (_required_) - `object`
An [OpenAPI Schema Object](http://swagger.io/specification/#schemaObject) 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](https://swagger.io/docs/specification/data-models/data-types/#required)
  - **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
```js
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' }
```

---
_Source: https://npm.io/package/openapi-sampler · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._