@grafana/openapi-to-k6

中文文档
0.4.1发布于 2026/01/20AGPL-3.0CommonJS近 30 天下载 1.5万

A CLI tool to generate helper modules for K6 from OpenAPI schema

原始使用文档
文档目录7 节
  1. Overview
  2. Getting started
  3. Options
  4. Developing locally
  5. Running E2E tests
  6. Packaging
  7. Releasing


Overview

The openapi-to-k6 repository is a tool designed to simplify the process of writing k6 scripts. It generates a TypeScript client from an OpenAPI specification that you can import in your k6 script to easily call your endpoints and have auto-completion in your IDE.

This lets developers easily create performance tests for their APIs based on their existing OpenAPI documentation.

Along with the client, it also generates a sample k6 script as an example of how to use the client.

The generated client exports a class with methods for each endpoint in the OpenAPI specification. You can create an instance of the class and use the methods to call the endpoints.

To see examples of the generated client and sample script, check out the examples directory.

Getting started

  1. Install the tool globally via:

    npm install -g @grafana/openapi-to-k6
    
  2. To start using the tool, either give the path to your OpenAPI schema file or provide a URL to your OpenAPI schema and the output path where you want to generate the client files:

    openapi-to-k6 <path-to-openapi-schema | url-to-openapi-schema> <output path>
    

    This will generate a TypeScript client and a sample k6 script in the corresponding directory.

    You can also supply the optional flag --include-sample-script to also generate a sample k6 script along with the client.

💡 Note: The tool supports both JSON and YAML format for OpenAPI schemas.

Options

The following are some of the configuration options supported by the tool:

  1. --mode or -m: Specify the mode to use for generating the client. The following options are available:

    1. single: This is the default mode used if nothing is specified. It generates the TypeScript client as a single file with all the types and implementation in a single file.
    2. split: This mode splits the types and implementation into separate files.
    3. tags: This modes splits your OpenAPI schema based on the tags and generates a separate client for each tag. If a route has no tag set, it will be available in the default.ts file.

    To check how the output looks for each mode, check out the examples directory.

  2. --only-tags: Filter the generated client to only include routes with specific tags from your OpenAPI schema. Multiple tags can be specified to include routes matching any of those tags. Routes without tags will be excluded. This is useful for generating focused clients that only contain the endpoints you need.

    For example: openapi-to-k6 <path-to-openapi-schema> <output path> --only-tags ItemsHeader will generate a client with only the routes that have the ItemsHeader tag. You can specify multiple tags by using multiple --only-tags flags or by separating them with spaces: --only-tags tag1 --only-tags tag2.

  3. --disable-analytics: Disable anonymous usage analytics reporting. You can also set an environment variable DISABLE_ANALYTICS=true to disable analytics.

  4. --include-sample-script: Generate a sample k6 script. The generated sample script uses the examples defined in the OpenAPI schema requests to make the script usable out of the box. If the examples are not defined, it will use Faker to generate random data.

  5. --verbose or -v : Enable verbose logging to see more detailed logging output.

  6. --help or -h : Show help message.

Developing locally

  1. Clone the repository:
git clone https://github.com/grafana/openapi-to-k6
  1. Install dependencies:
npm install
  1. Run the SDK generator from source:
npm run dev <path-to-openapi-schema> <output path>

This will generate the SDK files in the corresponding directory.

  1. Import them in your k6 script and run the script using the following command:
k6 run <path-to-k6-script>.ts

Running E2E tests

We have some end-to-end tests to ensure the generated SDK works as expected. To run these tests:

  1. Navigate to the test directory:
cd tests/e2e/
  1. Use Mockoon CLI to start the mock server which will create a mock server for the endpoints defined in the OpenAPI specification. This will run the mock server in a Docker container in background:
docker run -v ./schema.json:/tmp/schema.json -p 3000:3000 mockoon/cli:latest -d /tmp/schema.json
  1. Assuming you have already followed previous steps and have the environment set up, you can generate the SDK by using:
npm run dev -- ./schema.json ./sdk.ts
  1. Run the k6 script:
k6 run ./K6Script.ts

Packaging

  1. Run the command npm run build to package the project for distribution.
  2. Install the compiled package locally by using npm install . or npm install -g ..
  3. Use the CLI: k6-sdkgen <path-to-openapi-schema> <output path>.

Releasing

To release a new version of the tool, create a new release on GitHub with the new version number as a tag (for example, 0.1.0) and the release notes. After the release is created, GitHub Actions will automatically package the tool and publish it to npm.

Special mention to the the open-source library Orval which is used for the generation of the TypeScript client.

版本与发布记录

@grafana/openapi-to-k6 共发布 14 个版本,首次发布于 2024/10/21;过去 12 个月发布了 1 个版本。

版本发布日期距今
0.4.1latest2026/01/209 个月前
0.3.22025/02/041.8 年前
0.3.12025/01/141.8 年前
0.3.02024/11/142 年前
0.2.62024/11/082 年前
0.2.52024/11/012 年前

关于 @grafana/openapi-to-k6 的常见问题

@grafana/openapi-to-k6 是什么?

A CLI tool to generate helper modules for K6 from OpenAPI schema

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