@har-sdk/openapi-sampler
Version:
[](https://codeclimate.com/github/NeuraLegion/har-sdk/maintainability) [ • 6.45 kB
Markdown
# @har-sdk/openapi-sampler
[](https://codeclimate.com/github/NeuraLegion/har-sdk/maintainability)
[](https://codeclimate.com/github/NeuraLegion/har-sdk/test_coverage)
[](https://github.com/NeuraLegion/har-sdk/actions/workflows/auto-build.yml?query=branch%3Amaster+event%3Apush)
[](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.