# @har-sdk/openapi-sampler

> [![Maintainability](https://api.codeclimate.com/v1/badges/4acaec95c82465cb2c3d/maintainability)](https://codeclimate.com/github/NeuraLegion/har-sdk/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/4acaec95c82465cb2c3d/test_coverage

Latest version **2.4.2** (published 2025-04-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install @har-sdk/openapi-sampler
pnpm add @har-sdk/openapi-sampler
yarn add @har-sdk/openapi-sampler
bun add @har-sdk/openapi-sampler
```

## Health

**Score 55/100 (C)** — status: stable.

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

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 2.4.2 |
| Published | 2025-04-03 |
| First published | 2021-05-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 125.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | Artem Derevnjuk |
| Maintainers | derevnjuk, pmstss |
| Keywords | oas, swagger, instantiator, sampler |

## Links

- npm: https://www.npmjs.com/package/@har-sdk/openapi-sampler
- Repository: https://github.com/NeuraLegion/har-sdk
- Homepage: https://github.com/NeuraLegion/har-sdk/tree/master/packages/openapi-sampler#readme
- Issues: https://github.com/NeuraLegion/har-sdk/issues
- npm.io page: https://npm.io/package/@har-sdk/openapi-sampler

## Dependencies (4)

- [tslib](https://npm.io/package/tslib.md) ^2.3.1
- [randexp](https://npm.io/package/randexp.md) ^0.5.3
- [json-pointer](https://npm.io/package/json-pointer.md) ^0.6.2
- [@har-sdk/core](https://npm.io/package/@har-sdk/core.md) 1.5.0

## Alternatives

- [update-check](https://npm.io/package/update-check.md) — 4.0M weekly downloads
- [react-native-onesignal](https://npm.io/package/react-native-onesignal.md) — 134.5K weekly downloads
- [react-redux-toastr](https://npm.io/package/react-redux-toastr.md) — 33.7K weekly downloads
- [@nocobase/plugin-notification-manager](https://npm.io/package/@nocobase/plugin-notification-manager.md) — 2.0K weekly downloads
- [react-simple-toasts](https://npm.io/package/react-simple-toasts.md) — 1.9K weekly downloads

## Recent versions

- 2.4.2 (latest) — 2025-04-03
- 2.4.1 — 2025-03-25
- 2.4.0 — 2025-03-24
- 2.3.0 — 2025-03-24
- 2.2.1 — 2024-08-14
- 2.2.0 — 2024-02-27
- 2.1.4 — 2023-10-10
- 2.1.3 — 2023-09-14
- 2.1.2 — 2023-02-24
- 2.1.1 — 2023-02-23
- 2.1.0 — 2023-02-21
- 2.0.14 — 2023-02-21
- 2.0.13 — 2022-10-20
- 2.0.12 — 2022-07-12
- 2.0.11 — 2022-04-08
- … 15 more at https://npm.io/package/@har-sdk/openapi-sampler/versions

## README

# @har-sdk/openapi-sampler

[![Maintainability](https://api.codeclimate.com/v1/badges/4acaec95c82465cb2c3d/maintainability)](https://codeclimate.com/github/NeuraLegion/har-sdk/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/4acaec95c82465cb2c3d/test_coverage)](https://codeclimate.com/github/NeuraLegion/har-sdk/test_coverage)
[![Build Status](https://github.com/NeuraLegion/har-sdk/actions/workflows/auto-build.yml/badge.svg?branch=master)](https://github.com/NeuraLegion/har-sdk/actions/workflows/auto-build.yml?query=branch%3Amaster+event%3Apush)
[![NPM Downloads](https://img.shields.io/npm/dw/@har-sdk/openapi-sampler?label=NPM%20Downloads)](https://www.npmjs.com/package/@har-sdk/openapi-sampler)

This is a tool that generates samples based on OpenAPI payload/response schema.

- Supports a wide range of schema types and formats, including `allOf`, `additionalProperties`, and common string formats such as `email`, `password`, `date-time`, and more.
- Infers schema type automatically following the same rules as [json-schema-faker](https://www.npmjs.com/package/json-schema-faker#inferred-types).
- Supports `$ref` resolving.
- Produces deterministic and predictable output for a given input.
- Makes it easier and faster to generate sample data for OpenAPI schemas.
- Reduces errors and increases code quality by ensuring that generated samples follow the defined schema.

Using the `@har-sdk/openapi-sampler` package can save you a lot of time when you need to generate sample data for your OpenAPI schemas. With just a few lines of code, you can create realistic data objects that you can use for testing or documentation purposes.

## Installation

To install the package using npm, run the following command:

```bash
$ npm i --save @har-sdk/openapi-sampler
```

If you prefer using yarn, you can use the following command instead:

```bash
$ yarn add @har-sdk/openapi-sampler
```

## Usage

After installing, you can import the package in your code using the following import statement:

```js
import { sample } from '@har-sdk/openapi-sampler';
```

The `sample()` function is the main API provided by the package, and it takes three parameters:

| Option  | Description                                                                                                                                                                                                     |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| schema  | [OpenAPI Schema Object](http://swagger.io/specification/#schemaObject) that specifies the structure of the data you want to generate samples for.                                                               |
| options | Provides additional options for the sampler, such as skipping non-required properties, read-only properties, or write-only properties. You can find a full list of available options in the code example below. |
| spec    | Entire OpenAPI specification that the schema is taken from. This parameter is only required if the schema contains `$ref` references to external schemas.                                                       |

Here's an example of how to use the `sample()` function:

```js
import { sample } from '@har-sdk/openapi-sampler';

sample({
  type: 'object',
  properties: {
    a: { type: 'integer', minimum: 10 },
    b: { type: 'string', format: 'password', minLength: 10 },
    c: { type: 'boolean' }
  }
});
// { a: 10, b: 'pa$$word_q', c: true }
```

In this example, it is generating a sample data object based on a schema that contains three properties (`a`, `b`, and `c`).

Note, when `$ref` is used, the `spec` object must be provided so that the sampler can resolve the reference:

```js
import { sample } from '@har-sdk/openapi-sampler';

const spec = {
  // ...
  components: {
    schemas: {
      Pet: {
        type: 'object',
        properties: {
          id: {
            type: 'integer',
            format: 'int64'
          },
          name: {
            type: 'string'
          }
        }
      }
    }
  }
};

sample({ $ref: '#/components/schemas/Pet' }, {}, spec);
// { id: 42, name: 'lorem' }
```

By default, the sampler generates values for all properties defined in a schema, regardless of whether they are required or not. If you want to exclude non-required object properties, you can use the `skipNonRequired` option as follows:

```js
sample(
  {
    type: 'object',
    properties: {
      a: { type: 'string' },
      b: { type: 'string' }
    },
    required: ['b']
  },
  { skipNonRequired: true }
);
// { b: 'lorem' }
```

By default, all properties, including those marked as read or write-only, are included in the generated sample. However, if you want to exclude `readOnly` or `writeOnly` properties, you can use the `skipReadOnly` or `skipWriteOnly` options, respectively, as shown below:

```js
sample(
  {
    type: 'object',
    properties: {
      a: { type: 'string' },
      b: { type: 'string', readOnly: true }
    }
  },
  { skipReadOnly: true }
);
// { a: 'lorem' }
```

Note, the library recursively generates the entire sample object tree up to a maximum depth of 2 level to prevent infinite recursion. If you want to increase or decrease this maximum depth, you can use the `maxSampleDepth` option as follows:

```js
sample(schema, { maxSampleDepth: 20 });
```

Also, the library logs console warning messages when it encounters an unsupported schema. If you want to suppress these warning messages, you can use the quiet option as follows:

```js
sample(schema, { quiet: true });
```

When the schema comes from the specification which does not allow the `example` node to exist e.g. OAS 2.0 parameter definition, some vendors may provide such schema example value in OAS vendor extension nodes namely `x-example` or `x-examples`. If you want to include such kind of example values into the output, you can use the `includeVendorExamples` as shown below:

```js
sample(
  {
    'type': 'string',
    'x-example': 'some_value'
  },
  { includeVendorExamples: true }
);
// some_value
```

## License

Copyright © 2023 [Bright Security](https://brightsec.com/).

This project is licensed under the MIT License - see the [LICENSE file](https://github.com/NeuraLegion/har-sdk/blob/master/LICENSE) for details.

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