@grafana/openapi-to-k6 0.1.2 → 0.2.1

package/.github/workflows/publish.yaml

@@ -19,13 +19,13 @@ jobs:
           node-version: '21'
           registry-url: 'https://registry.npmjs.org'
           scope: '@grafana'
+          cache: 'npm'
+          cache-dependency-path: 'package-lock.json'
       - run: npm ci
       - name: Update version in package.json
         run: |
           NEW_VERSION=${{ github.event.release.tag_name }}
           npm version $NEW_VERSION --no-git-tag-version
-      - name: Update generated examples
-        run: npm run update-examples
       - name: Commit updated package.json
         run: |
           git config --global user.name 'github-actions[bot]'

package/.github/workflows/tests.yaml

@@ -12,7 +12,9 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: '21.5.0'
+          node-version: '21'
+          cache: 'npm'
+          cache-dependency-path: 'package-lock.json'
       - run: npm ci
       - run: npm run lint
       - run: npm test
@@ -22,10 +24,15 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: '21.5.0'
+          node-version: '21'
+          cache: 'npm'
+          cache-dependency-path: 'package-lock.json'
       - run: npm ci
       - name: Generate SDK for E2E tests
-        run: npm run dev -- ./tests/e2e/schema.json ./tests/e2e/sdk.ts --disable-analytics
+        run: |
+          npm run dev -- ./tests/e2e/schema.json ./tests/e2e/single/sdk.ts --disable-analytics --mode single
+          npm run dev -- ./tests/e2e/schema.json ./tests/e2e/split/sdk.ts --disable-analytics --mode split
+          npm run dev -- ./tests/e2e/schema.json ./tests/e2e/tags/sdk.ts --disable-analytics --mode tags
       - name: Start Mockoon CLI
         uses: mockoon/cli-action@v2
         with:
@@ -35,17 +42,18 @@ jobs:
       - uses: grafana/setup-k6-action@v1
       - uses: grafana/run-k6-action@v1
         with:
-          path: './tests/e2e/k6Script.ts'
+          path: './tests/e2e/*/k6Script.ts'
           flags: '--compatibility-mode=experimental_enhanced'
           inspect-flags: '--compatibility-mode=experimental_enhanced'
   run-examples:
     runs-on: ubuntu-latest
-    needs: [test, e2e-test]
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: '21.5.0'
+          node-version: '21'
+          cache: 'npm'
+          cache-dependency-path: 'package-lock.json'
       - run: npm ci
       - name: Update examples
         run: npm run update-examples

package/README.md

@@ -1,10 +1,15 @@
-# openapi-to-k6
-
-<p align="center">⚠️</p>
-
-***This tool is currently in the experimental stage. Expect bugs, incomplete features, and breaking changes as development progresses. Use at your own risk, and please report any issues or feedback to help us improve.***
-
----
+<div align="center">
+
+  <img
+    src="./images/openapi-to-k6.png"
+    width="600"
+    style="pointer-events: none;" />
+  <br />
+  <hr/>
+  <p align="center">⚠️</p>
+<b>This tool is currently in the experimental stage. Expect bugs, incomplete features, and breaking changes as development progresses. Use at your own risk, and please report any issues or feedback to help us improve.</b>
+<hr/>
+</div>
 
 ## Overview
 
@@ -17,16 +22,51 @@ OpenAPI documentation.
 
 Along with the client, it also generates a sample k6 script as an example of how to use the client.
 
-To get started, install the tool with npm via `npm install openapi-to-k6` and run it to convert your
-OpenAPI specification to a TypeScript client for k6.
+The generated client exports a class with methods for each endpoint in the OpenAPI specification. You can create
+a instance of the class and use the methods to call the endpoints.
 
-To take a look at a few examples of how the generated client and sample script looks, check out the [examples](./examples) directory.
+To take a look at a few examples of how the generated client looks and sample script looks, check out the [examples](./examples) directory.
 
-Note: Optional usage analytics are gathered to make the tool better. To disable this, use the option
-`--disable-analytics` or set an environment variable `DISABLE_ANALYTICS=true`.
 
 ## Getting started
 
+1. Install the tool globally via
+
+    ```shell
+    npm install -g @grafana/openapi-to-k6
+    ```
+
+2. To start using the tool either give path to your OpenAPI schema file or provide a URL to your Open
+   API schema and the output path where you want to generate the client files.
+
+    ```shell
+    openapi-to-k6 <path-to-openapi-schema | url-to-openapi-schema> <output path>
+    ```
+
+    This will the 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 schema.
+
+### Options
+
+Following are some of the configuration options supported by the tool.
+
+1. `--mode` or `-m`: Specify the mode to use for generating the client. Following are available options:
+   1. `single`: This is the default mode used is nothing is specified. It generated 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 `default.ts` file.
+
+   To check how the output looks for each mode, check out the [examples](./examples) directory.
+2. `--disable-analytics`: Disable anonymous usage analytics reporting which helping making the tool better. You can also set an environment variable `DISABLE_ANALYTICS=true` to disable the analytics.
+3. `--include-sample-script`: Generate a sample k6 script.
+4. `--verbose` or `-v` : Enable verbose logging to see more detailed logging output.
+5. `--help` or `-h` : Show help message.
+
+## Developing locally
+
 1. Clone the repository
 
 ```shell
@@ -69,7 +109,7 @@ cd tests/e2e/
 This will run the mock server in a docker container in background.
 
 ```shell
-docker run -d -v ./schema.json:/tmp/schema.json -p 3000:3000 mockoon/cli:latest -d /tmp/schema.json
+docker run -v ./schema.json:/tmp/schema.json -p 3000:3000 mockoon/cli:latest -d /tmp/schema.json
 ```
 
 3. Assuming you have already followed previous steps and have the environment set up, you can generate the SDK by using
@@ -90,4 +130,4 @@ k6 run --compatibility-mode=experimental_enhanced ./K6Script.ts
 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>`
 
-Special thanks for the the open-source library [Orval](https://orval.dev/) to facilitate the generation of these SDK.
+Special mention for the the open-source library [Orval](https://orval.dev/) which is used for the generation of the TypeScript client.

package/dist/analytics.js

@@ -37,7 +37,7 @@ function getAnonymousUserId() {
  * @param packageDetails - Details of the openapi-to-k6 package.
  * @returns
  */
-function generateDefaultAnalyticsData(packageDetails) {
+function generateDefaultAnalyticsData(packageDetails, isSampleK6ScriptGenerated) {
     const defaultAnalyticsData = {
         generatedRequestsCount: {
             post: 0,
@@ -47,6 +47,7 @@ function generateDefaultAnalyticsData(packageDetails) {
             delete: 0,
             head: 0,
         },
+        isSampleK6ScriptGenerated,
         openApiSpecVersion: '',
         toolVersion: packageDetails.version,
         anonymousUserId: getAnonymousUserId(),

package/dist/cli.js

@@ -16,13 +16,26 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const chalk_1 = __importDefault(require("chalk"));
 const commander_1 = require("commander");
 const analytics_1 = require("./analytics");
+const constants_1 = require("./constants");
 const generator_1 = __importDefault(require("./generator"));
 const helper_1 = require("./helper");
 const logger_1 = require("./logger");
 const program = new commander_1.Command();
 const packageDetails = (0, helper_1.getPackageDetails)();
+/**
+ * Validate that the mode argument is one of the supported modes.
+ *
+ * @param {string} value - The mode value to validate
+ * @return {Mode} - The validated mode value
+ */
+function validateMode(value) {
+    if (!Object.values(constants_1.Mode).includes(value)) {
+        throw new commander_1.InvalidArgumentError(`Supported modes: ${Object.values(constants_1.Mode).join(', ')}`);
+    }
+    return value;
+}
 function generateSDK(_a) {
-    return __awaiter(this, arguments, void 0, function* ({ openApiPath, outputDir, shouldGenerateSampleK6Script, analyticsData, }) {
+    return __awaiter(this, arguments, void 0, function* ({ openApiPath, outputDir, shouldGenerateSampleK6Script, analyticsData, mode, }) {
         logger_1.logger.logMessage('Generating TypeScript client for k6...\n');
         logger_1.logger.logMessage(`OpenAPI schema: ${openApiPath}`);
         logger_1.logger.logMessage(`Output: ${outputDir}\n`);
@@ -31,6 +44,7 @@ function generateSDK(_a) {
             outputDir,
             shouldGenerateSampleK6Script,
             analyticsData,
+            mode,
         });
         if (shouldGenerateSampleK6Script) {
             logger_1.logger.logMessage(`TypeScript client and sample k6 script generated successfully.`, chalk_1.default.green);
@@ -46,14 +60,13 @@ program
     .version(packageDetails.version)
     .argument('<openApiPath>', 'Path or URL for the OpenAPI schema file')
     .argument('<outputDir>', 'Directory where the SDK should be generated')
+    .option('-m, --mode <string>', `mode to use for generating the client. Valid values - ${Object.values(constants_1.Mode).join(', ')}`, validateMode, constants_1.Mode.SINGLE)
     .option('-v, --verbose', 'enable verbose mode to show debug logs')
-    .option('--no-sample-script', 'disable generating sample k6 script')
+    .option('--include-sample-script', 'generate a sample k6 script')
     .option('--disable-analytics', 'disable anonymous usage data collection')
     .action((openApiPath, outputDir, options) => __awaiter(void 0, void 0, void 0, function* () {
     let analyticsData;
     const shouldDisableAnalytics = options.disableAnalytics || process.env.DISABLE_ANALYTICS === 'true';
-    const shouldDisableSampleScript = options.disableSampleScript ||
-        process.env.DISABLE_SAMPLE_SCRIPT === 'true';
     if (options.verbose) {
         logger_1.logger.setVerbose(true);
         logger_1.logger.debug('Verbose mode enabled, showing debug logs');
@@ -63,7 +76,7 @@ program
     }
     else {
         logger_1.logger.debug('Anonymous usage data collection enabled');
-        analyticsData = (0, analytics_1.generateDefaultAnalyticsData)(packageDetails);
+        analyticsData = (0, analytics_1.generateDefaultAnalyticsData)(packageDetails, !!options.includeSampleScript);
     }
     logger_1.logger.debug(`
             Supplied OpenAPI schema: ${openApiPath}
@@ -73,8 +86,9 @@ program
         yield generateSDK({
             openApiPath,
             outputDir,
-            shouldGenerateSampleK6Script: !shouldDisableSampleScript,
+            shouldGenerateSampleK6Script: !!options.includeSampleScript,
             analyticsData,
+            mode: options.mode,
         });
     }
     catch (error) {

package/dist/constants.js

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.K6_SCRIPT_TEMPLATE = exports.SAMPLE_K6_SCRIPT_FILE_NAME = exports.DEFAULT_SCHEMA_TITLE = void 0;
+exports.Mode = exports.K6_SCRIPT_TEMPLATE = exports.SAMPLE_K6_SCRIPT_FILE_NAME = exports.DEFAULT_SCHEMA_TITLE = void 0;
 exports.DEFAULT_SCHEMA_TITLE = 'K6Client';
 exports.SAMPLE_K6_SCRIPT_FILE_NAME = 'k6-script.sample.ts';
 exports.K6_SCRIPT_TEMPLATE = `
 import { {{clientFunctionName}} } from '{{clientPath}}'
 
 const baseUrl = '<BASE_URL>';
-const client = {{clientFunctionName}}({ baseUrl })
+const client = new {{clientFunctionName}}({ baseUrl })
 
 export default function () {
     {{#each clientFunctionsList}}
@@ -19,3 +19,9 @@ export default function () {
     {{/each}}
 }
 `;
+var Mode;
+(function (Mode) {
+    Mode["SINGLE"] = "single";
+    Mode["SPLIT"] = "split";
+    Mode["TAGS"] = "tags";
+})(Mode || (exports.Mode = Mode = {}));

package/dist/{generator.js → generator/index.js}

@@ -15,10 +15,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const orval_1 = __importDefault(require("orval"));
 const path_1 = __importDefault(require("path"));
-const constants_1 = require("./constants");
-const helper_1 = require("./helper");
-const k6SdkClient_1 = require("./k6SdkClient");
-const logger_1 = require("./logger");
+const constants_1 = require("../constants");
+const helper_1 = require("../helper");
+const logger_1 = require("../logger");
+const k6Client_1 = require("./k6Client");
 const outputOverrider = helper_1.OutputOverrider.getInstance();
 const packageDetails = (0, helper_1.getPackageDetails)();
 const generatedFileHeaderGenerator = (info) => {
@@ -44,10 +44,7 @@ const afterAllFilesWriteHandler = (filePaths) => __awaiter(void 0, void 0, void
         }
     }
 });
-exports.default = (_a) => __awaiter(void 0, [_a], void 0, function* ({ openApiPath, outputDir, shouldGenerateSampleK6Script, analyticsData, }) {
-    const schemaDetails = {
-        title: '',
-    };
+exports.default = (_a) => __awaiter(void 0, [_a], void 0, function* ({ openApiPath, outputDir, shouldGenerateSampleK6Script, analyticsData, mode, }) {
     /**
      * Note!
      * 1. override.requestOptions is not supported for the custom K6 client
@@ -58,8 +55,8 @@ exports.default = (_a) => __awaiter(void 0, [_a], void 0, function* ({ openApiPa
             input: openApiPath,
             output: {
                 target: outputDir,
-                mode: 'single',
-                client: () => (0, k6SdkClient_1.getK6ClientBuilder)(schemaDetails, shouldGenerateSampleK6Script, analyticsData),
+                mode: mode,
+                client: () => (0, k6Client_1.getK6ClientBuilder)(shouldGenerateSampleK6Script, analyticsData),
                 override: {
                     header: generatedFileHeaderGenerator,
                 },
@@ -70,7 +67,4 @@ exports.default = (_a) => __awaiter(void 0, [_a], void 0, function* ({ openApiPa
             },
         });
     }));
-    if (!schemaDetails.title) {
-        logger_1.logger.warning('Could not find schema title in the OpenAPI spec. Please provide a `title` in the schema in `info` block to generate proper file names');
-    }
 });