@har-sdk/openapi-sampler

中文文档
2.4.2发布于 2025/04/03MITTypeScriptESM + CJS近 30 天下载 2.5万
中文使用文档
文档目录3 节
  1. 安装
  2. 使用量
  3. 许可证

@har-sdk/ opanapi- sampler (英语)

Maintainability Test Coverage Build Status NPM Downloads

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

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

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

安装

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

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

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

$ yarn add @har-sdk/openapi-sampler

使用量

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

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

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

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

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

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 必须提供对象,以便取样者能够解析引用:

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 选项如下:

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

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

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

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

sample(schema, { maxSampleDepth: 20 });

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

sample(schema, { quiet: true });

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

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

许可证

版权 2023 亮度安全。 。 。 .

这个项目根据麻省理工学院许可证颁发——见 自由文件 详细情况.

版本与发布记录

@har-sdk/openapi-sampler 共发布 30 个版本,首次发布于 2021/05/20;过去 12 个月发布了 0 个版本。

版本发布日期距今
2.4.2latest2025/04/031.6 年前
2.4.12025/03/251.6 年前
2.4.02025/03/251.6 年前
2.3.02025/03/241.6 年前
2.2.12024/08/142 年前
2.2.02024/02/272 年前

关于 @har-sdk/openapi-sampler 的常见问题

@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 和提交记录判断。