# @grafana/openapi-to-k6 中文文档

规范地址：https://npmcn.com/package/%40grafana/openapi-to-k6/

版本：0\.4\.1
npm 元数据更新时间：2026-07-21T17:56:54.205Z
中文译文更新时间：2026-11-16T22:06:13.831Z
软件包许可：AGPL-3\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40grafana/openapi-to-k6
原文对照：https://npmcn.com/package/%40grafana/openapi-to-k6/?lang=original
项目主页：https://github.com/grafana/openapi-to-k6#readme
源码仓库：https://github.com/grafana/openapi-to-k6

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

- 包体积（解压后）：413 kB，151 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：10 个
- 首次发布：2024-10-21T14:34:49.797Z
- 最新版本发布：2026-01-19T16:35:27.193Z
- 近 30 天下载量：15135（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 1 个）

## 中文简介

从 OpenAPI schema 为 K6 生成辅助模块的 CLI 工具

## 安装

```sh
npm install @grafana/openapi-to-k6
```

也可以使用：`pnpm add @grafana/openapi-to-k6`、`yarn add @grafana/openapi-to-k6`、`bun add @grafana/openapi-to-k6`

## README

![](https://raw.githubusercontent.com/grafana/openapi-to-k6/main/images/openapi-to-k6.png)  

## 概览

这个 _打开api- to- k6_ 寄存器是一个旨在简化 k6 脚本编写过程的工具. 它从 OpenAPI 规格生成一个 TypeScript 客户端, 您可以在您的 k6 脚本中导入到 方便的调用您的端点,并在您的 IDE 中自动完成 .

这样可以让开发者根据已有的API轻松创建性能测试 OpenAPI 文档.

它与客户端一起,还生成了样本 k6 脚本,作为如何使用客户端的例子.

生成的客户端会输出一个类别,其中包含OpenAPI规格中每个端点的方法. 您可以创建 并使用方法调用终点.

要查看生成客户端和样本脚本的示例, 请检查 [实例](https://npmcn.com/package/%40grafana/openapi-to-k6/examples) 目录.

## 开始

1.  通过以下方式在全球安装该工具:
    
    ```shell
    npm install -g @grafana/openapi-to-k6
    ```
    
2.  要开始使用此工具, 要么给您的 OpenAPI schema 文件提供路径, 要么为您的 OpenAPI schema 提供 URL 和您想要生成客户端文件的输出路径 :
    
    ```shell
    openapi-to-k6 <path-to-openapi-schema | url-to-openapi-schema> <output path>
    ```
    
    这将生成一个 TypeScript 客户端和相应的目录中的样本 k6 脚本 .
    
    您也可以提供可选旗帜 `--include-sample-script` 生成样本 k6 脚本 与客户.
    

💡 _说明_:该工具既支持JSON格式,也支持OpenAPI schemas格式.

### 选项

以下是该工具所支持的一些配置选项:

1.  `--mode` 或者说 `-m`:指定生成客户端所使用的模式。 有以下备选方案:
    
    1.  `single`: 如果没有指定, 则使用默认模式 。 它将 TypeScript 客户端生成为单一文件,其中包含所有类型和执行在一个文件中.
    2.  `split`: 此模式将类型和执行拆分为单独的文件.
    3.  `tags`: 此模式会根据标签拆分您的 OpenAPI 计划, 并为每个标签生成单独的客户端 。 如果一个路由没有设置标签,则可以在 `default.ts` 文档.
    
    要检查每个模式的输出外观, 请检查 [实例](https://npmcn.com/package/%40grafana/openapi-to-k6/examples) 目录.
    
2.  `--only-tags`: 过滤生成的客户端, 只包含您 OpenAPI schema 中带有特定标记的路由 。 可以指定多个标记,以包括匹配其中任何一个标记的路线. 没有标记的路线将被排除在外. 这对生成只包含您需要的端点的焦点客户端很有用.
    
    例如: `openapi-to-k6 <path-to-openapi-schema> <output path> --only-tags ItemsHeader` 将生成仅包含路径的客户端 `ItemsHeader` 标签。 您可以通过使用多个标签指定多个标签 `--only-tags` 标记或以空格分隔: `--only-tags tag1 --only-tags tag2`。 。 。 .
    
3.  `--disable-analytics`: 禁用匿名用途分析报告. 您也可以设置环境变量 `DISABLE_ANALYTICS=true` 以禁用分析.
    
4.  `--include-sample-script`: 生成样本 k6 脚本. 生成的样本脚本使用OpenAPI schema请求中定义的例子,使脚本可用出框. 如果不定义示例,它将使用Faker生成随机数据.
    
5.  `--verbose` 或者说 `-v` : 启用动词日志可以看到更详细的日志输出.
    
6.  `--help` 或者说 `-h` : 显示帮助消息 .
    

## 地方发展

1.  清除仓库 :

```shell
git clone https://github.com/grafana/openapi-to-k6
```

2.  安装依赖性 :

```shell
npm install
```

3.  从源头运行 SDK 生成器 :

```shell
npm run dev <path-to-openapi-schema> <output path>
```

这将生成相应的目录中的 SDK 文件 .

4.  在您的 k6 脚本中导入并使用以下命令运行脚本 :

```shell
k6 run <path-to-k6-script>.ts
```

## 运行 E2E 测试

我们有一些端到端的测试,以确保生成的SDK作品如所预期. 为了进行这些测试:

1.  导航到测试目录 :

```shell
cd tests/e2e/
```

2.  使用 Mokoon CLI 启动模拟服务器, 这将为 OpenAPI 规格定义的终点创建模拟服务器 . 这将在背景的 Docker 容器中运行模拟服务器 :

```shell
docker run -v ./schema.json:/tmp/schema.json -p 3000:3000 mockoon/cli:latest -d /tmp/schema.json
```

3.  假设您已经遵循了之前的步骤并设置了环境,您可以通过使用:

```shell
npm run dev -- ./schema.json ./sdk.ts
```

4.  运行 k6 脚本 :

```shell
k6 run ./K6Script.ts
```

## 包装

1.  运行命令 `npm run build` 来包装项目以供分发.
2.  本地安装编译软件包 `npm install .` 或者说 `npm install -g .`。 。 。 .
3.  使用 CLI : `k6-sdkgen <path-to-openapi-schema> <output path>`。 。 。 .

## 释放

要发布该工具的新版本,在GitHub上创建以新版本编号为标签的新版本(例如, `0.1.0`)和发行笔记. 在发行创建后,GitHub Actions将自动将工具包入并发布到npm.

特别提及开源库 [阴性](https://orval.dev/) 用于生成 TypeScript 客户端.

## 常见问题

### @grafana/openapi-to-k6 是什么？

从 OpenAPI schema 为 K6 生成辅助模块的 CLI 工具

### 如何安装 @grafana/openapi-to-k6？

在项目目录运行 npm install @grafana/openapi-to-k6，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 openapi-to-k6，可以用 npx openapi-to-k6 直接运行。

### @grafana/openapi-to-k6 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/grafana\_\_openapi-to-k6 是否存在。

### @grafana/openapi-to-k6 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @grafana/openapi-to-k6 可以商用吗？

@grafana/openapi-to-k6 使用 AGPL-3\.0 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @grafana/openapi-to-k6 的下载量有多少？

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

### @grafana/openapi-to-k6 还在维护吗？

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

