# @har-sdk/openapi-sampler 中文文档

规范地址：https://npmcn.com/package/%40har-sdk/openapi-sampler/

版本：2\.4\.2
npm 元数据更新时间：2026-10-21T10:39:58.450Z
中文译文更新时间：2026-11-17T09:35:59.801Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40har-sdk/openapi-sampler
原文对照：https://npmcn.com/package/%40har-sdk/openapi-sampler/?lang=original
项目主页：https://github.com/NeuraLegion/har-sdk/tree/master/packages/openapi-sampler#readme
源码仓库：https://github.com/NeuraLegion/har-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：128 kB，54 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2021-05-19T22:03:05.615Z
- 最新版本发布：2025-04-03T10:14:53.401Z
- 近 30 天下载量：25003（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 0 个）

## 中文简介

[![Maintainability](https://api.codeclimate.com/v1/badges/4acaec95c82465cb2c3d/maintainability)](https://codeclimate.com/github/NeuraLegion/har-sdk/maintainability) \[! \[试播 ([https://api.codeclimate.com/v1/badges/4acaec95c82465cb2c3d/test coverage (中文(简体) )](https://api.codeclimate.com/v1/badges/4acaec95c82465cb2c3d/test_coverage)

## 安装

```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`

## README

# @har-sdk/ opanapi- 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)

这是一个基于OpenAPI有效载荷/应答计划生成样本的工具.

-   支持广泛的计划类型和格式,包括: `allOf`, (中文(简体) ), `additionalProperties`,以及常见的字符串格式,例如 `email`, (中文(简体) ), `password`, (中文(简体) ), `date-time`还有更多.
-   推断计划类型自动遵循与规则相同的规则 [json-schema- faker (英语)](https://www.npmjs.com/package/json-schema-faker#inferred-types)。 。 。 .
-   支助 `$ref` 解决.
-   为某一投入提供确定性和可预期的产出.
-   使得为OpenAPI schemas生成样本数据更加容易和快.
-   通过确保生成的样本遵循定义的策略来减少出错并提升代码质量.

使用 `@har-sdk/openapi-sampler` 当您需要为您的 OpenAPI 计划生成样本数据时, 软件包可以节省您很多时间。 仅用几行代码就可以创建现实的数据对象,用于测试或文档目的.

## 安装

要使用 npm 安装软件包, 请运行以下命令 :

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

如果您喜欢使用纱线,您可以使用以下命令:

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

## 使用量

安装后,您可以使用以下导入语句导入代码中的软件包:

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

这个 `sample()` 函数是软件包提供的主要API,它需要三个参数:

| 选项 | 说明 |
| --- | --- |
| 计划 | [OpenAPI Schema 对象](http://swagger.io/specification/#schemaObject) 指定要生成样本的数据的结构. |
| 选项 | 为采样器提供附加选项,例如跳过非必需属性,只读属性,或只写属性. 您可以在下面的代码示例中找到一个完整的可用选项列表. |
| 光谱 | 全部 OpenAPI 规格 : 计划取自 。 此参数只有在计划包含 `$ref` 参考外部计划. |

这是如何使用 `sample()` 函数 :

```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 }
```

在这个例子中,它正在生成一个基于包含三个属性(即:`a`, (中文(简体) ), `b`,以及 `c`) (中文(简体) ).

说明,何时 `$ref` 用于: `spec` 必须提供对象,以便取样者能够解析引用:

```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' }
```

默认情况下,采样器会生成一个图中定义的所有属性的值,无论是否需要. 如果您想要排除非必需对象属性, 您可以使用 `skipNonRequired` 选项如下:

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

默认情况下,所有属性,包括被标记为只读或只写属性,都包含在生成的样本中. 然而,如果你想排除 `readOnly` 或者说 `writeOnly` 属性,您可以使用 `skipReadOnly` 或者说 `skipWriteOnly` 选项,分别如下:

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

注意,库会递归地生成整个样本对象树,最大深度可达2个关卡来防止无限地重复. 如果您想要增减此最大深度, 您可以使用 `maxSampleDepth` 选项如下:

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

另外,库日志在遇到不支持的计划时会控制警告消息. 如果您想要压制这些警告信息, 您可以使用静态选项如下 :

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

当计划来自不允许 `example` 例如,OAS 2.0参数定义,一些供应商可能在OAS供应商扩展节点中提供这种计划实例值,即 `x-example` 或者说 `x-examples`。如果想要在输出中包含此类实例值,可以使用 `includeVendorExamples` 如下所示:

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

## 许可证

版权 2023 [亮度安全](https://brightsec.com/)。 。 。 .

这个项目根据麻省理工学院许可证颁发——见 [自由文件](https://github.com/NeuraLegion/har-sdk/blob/master/LICENSE) 详细情况.

## 常见问题

### @har-sdk/openapi-sampler 是什么？

\[\! \[试播 \(https://api\.codeclimate\.com/v1/badges/4acaec95c82465cb2c3d/test coverage \(中文\(简体\) \)

### 如何安装 @har-sdk/openapi-sampler？

在项目目录运行 npm install @har-sdk/openapi-sampler，或使用 pnpm add / yarn add / bun add。

### @har-sdk/openapi-sampler 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @har-sdk/openapi-sampler 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @har-sdk/openapi-sampler 可以商用吗？

@har-sdk/openapi-sampler 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @har-sdk/openapi-sampler 的下载量有多少？

根据 npm 官方下载统计，@har-sdk/openapi-sampler 在 2026/10/17 – 2026/11/15 这 30 天内被下载 25,003 次，日均约 833 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @har-sdk/openapi-sampler 还在维护吗？

最新版本 2\.4\.2 发布于 2025/04/03（1\.6 年前）；至今共发布 30 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/05/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

