@openapi-qraft/openapi-typescript-plugin 1.0.1

package/src/__snapshots__/with-extra-options.ts.snapshot.ts

@@ -0,0 +1,259 @@
+/**
+ * This file was auto-generated by @openapi-qraft/cli.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+    "/files": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get a files by ID */
+        get: operations["get_files"];
+        put?: never;
+        /** Upload a files by ID */
+        post: operations["post_files"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/files/list": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a file list
+         * @deprecated
+         */
+        get: operations["get_file_list"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        EntityOnboardingDocuments: {
+            verification_document_front: string;
+            verification_document_back?: string;
+        };
+        ErrorSchema: {
+            message: string;
+        };
+        ErrorSchemaResponse: {
+            error: components["schemas"]["ErrorSchema"];
+        };
+        HTTPValidationError: {
+            detail?: components["schemas"]["ValidationError"][];
+        };
+        ValidationError: {
+            loc: (string | number)[];
+            msg: string;
+            type: string;
+        };
+        ApprovalPolicyUpdate: {
+            /** @description The name of the approval policy. */
+            name?: string;
+            /** @description A brief description of the approval policy. */
+            description?: string;
+            /** @description A list of JSON objects that represents the approval policy script. The script contains the logic that determines whether an action should be sent to approval. This field is required, and it should contain at least one script object. */
+            script?: (boolean | number | string | unknown[] | Record<string, never>)[];
+            /**
+             * @description A JSON object that represents the trigger for the approval policy. The trigger specifies the event that will trigger the policy to be evaluated.
+             * @example {amount >= 1000}
+             */
+            trigger?: boolean | number | string | unknown[] | Record<string, never>;
+            /** @description A string that represents the current status of the approval policy. */
+            status?: components["schemas"]["ApprovalPolicyStatus"];
+        };
+        /**
+         * @description An enumeration.
+         * @enum {string}
+         */
+        ApprovalPolicyStatus: "active" | "deleted" | "pending";
+        ApprovalPolicyResource: {
+            /** @description The name of the approval policy. */
+            name: string;
+            /** @description A brief description of the approval policy. */
+            description: string;
+            /** Format: uuid */
+            id: string;
+        };
+        /**
+         * @description An enumeration.
+         * @enum {string}
+         */
+        OrderEnum: "asc" | "desc";
+        FilesResponse: {
+            data: components["schemas"]["FileResponse"][];
+        };
+        FileResponse: {
+            /** Format: uuid */
+            id: string;
+            file_type: string;
+            name: string;
+            url: string;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    get_files: {
+        parameters: {
+            query: {
+                id__in: string[];
+                /** @description Page number */
+                page?: string;
+            };
+            header: {
+                /** @example 2023-06-04 */
+                "x-monite-version": string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        header?: {
+                            /** Format: date */
+                            "x-monite-version"?: string;
+                        };
+                        query?: {
+                            id__in?: string[];
+                            /** @description Page number */
+                            page?: string;
+                        };
+                    };
+                };
+            };
+            /** @description Method Not Allowed */
+            405: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorSchemaResponse"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+            /** @description Internal Server Error */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorSchemaResponse"];
+                };
+            };
+        };
+    };
+    post_files: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "multipart/form-data": {
+                    /** Format: binary */
+                    file?: string;
+                    file_description?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        body?: {
+                            file?: string;
+                            file_description?: string;
+                        };
+                    };
+                };
+            };
+            /** @description Internal Server Error */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorSchemaResponse"];
+                };
+            };
+        };
+    };
+    get_file_list: {
+        parameters: {
+            query?: {
+                id__in?: string[];
+            };
+            header?: {
+                /** @example 2023-06-04 */
+                "x-monite-version"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FilesResponse"];
+                };
+            };
+            /** @description Internal Server Error */
+            default: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorSchemaResponse"];
+                };
+            };
+        };
+    };
+}

package/src/generateSchemaTypes.ts

@@ -0,0 +1,77 @@
+import { createConfig } from '@redocly/openapi-core';
+
+import type { Readable } from 'node:stream';
+import openapiTS, {
+  astToString,
+  type OpenAPI3,
+  type OpenAPITSOptions,
+  SchemaObject,
+} from 'openapi-typescript';
+import ts from 'typescript';
+
+export async function generateSchemaTypes(
+  schema: string | URL | OpenAPI3 | Readable | Buffer,
+  {
+    silent,
+    args,
+  }: {
+    silent: boolean;
+    args: Pick<
+      OpenAPITSOptions,
+      | 'additionalProperties'
+      | 'alphabetize'
+      | 'arrayLength'
+      | 'defaultNonNullable'
+      | 'emptyObjectsUnknown'
+      | 'enum'
+      | 'excludeDeprecated'
+      | 'exportType'
+      | 'immutable'
+      | 'pathParamsAsTypes'
+      | 'propertiesRequiredByDefault'
+    > & {
+      blobFromBinary?: boolean;
+    };
+  }
+) {
+  return astToString(
+    await openapiTS(schema, {
+      transform: args.blobFromBinary ? transformFormatBinary : undefined,
+      additionalProperties: args.additionalProperties,
+      alphabetize: args.alphabetize,
+      arrayLength: args.arrayLength,
+      // contentNever: args.contentNever, // todo::add `contentNever` in new version
+      defaultNonNullable: args.defaultNonNullable,
+      emptyObjectsUnknown: args.emptyObjectsUnknown,
+      enum: args.enum,
+      excludeDeprecated: args.excludeDeprecated,
+      exportType: args.exportType,
+      immutable: args.immutable,
+      pathParamsAsTypes: args.pathParamsAsTypes,
+      redocly: await createConfig({}, { extends: ['minimal'] }),
+      propertiesRequiredByDefault: args.propertiesRequiredByDefault,
+      silent,
+    })
+  );
+}
+
+function transformFormatBinary(schemaObject: SchemaObject) {
+  if (schemaObject.format !== 'binary') return;
+
+  return {
+    schema: schemaObject.nullable
+      ? ts.factory.createUnionTypeNode([
+          ts.factory.createTypeReferenceNode(
+            ts.factory.createIdentifier('Blob'),
+            undefined
+          ),
+          ts.factory.createLiteralTypeNode(ts.factory.createNull()),
+        ])
+      : ts.factory.createTypeReferenceNode(
+          ts.factory.createIdentifier('Blob'),
+          undefined
+        ),
+    // questionToken will be inferred by `openapiTS`, if true, it will force `?` for parameter
+    questionToken: false,
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import { plugin } from './plugin.js';
+
+export default plugin;

package/src/lib/createOpenapiTypesImportPath.ts

@@ -0,0 +1,33 @@
+/**
+ * Create the import path for the OpenAPI types file.
+ * @param openapiTypesFileName The file name of the OpenAPI types file. Eg: `schema.d.ts`
+ * @param explicitImportExtensions Whether to include explicit `.js` extensions in the import path.
+ */
+export function createOpenapiTypesImportPath(
+  openapiTypesFileName: string,
+  explicitImportExtensions: boolean
+) {
+  return explicitImportExtensions
+    ? `../${getTypeScriptFileBaseName(openapiTypesFileName)}.js`
+    : `../${openapiTypesFileName}`;
+}
+
+/**
+ * Get the base name of the TypeScript file without the extension.
+ * Removes `.d.ts` or `.ts` from the file name.
+ */
+function getTypeScriptFileBaseName(openapiTypesFileName: string) {
+  return openapiTypesFileName.replace(getTsExtensionRegexp(), '');
+}
+
+/**
+ * Check if the file name is a valid TypeScript file name.
+ * Eg: `schema.d.ts`, `schema.ts`
+ */
+export function isValidTypeScriptFileName(fileName: string) {
+  return getTsExtensionRegexp().test(fileName);
+}
+
+function getTsExtensionRegexp() {
+  return /\.(d\.)?ts$/;
+}

package/src/plugin.ts

@@ -0,0 +1,140 @@
+import { fileHeader } from '@openapi-qraft/plugin/lib/fileHeader';
+import { formatFileHeader } from '@openapi-qraft/plugin/lib/formatFileHeader';
+import { QraftCommandPlugin } from '@openapi-qraft/plugin/lib/QraftCommandPlugin';
+
+import { CommanderError } from 'commander';
+
+import { generateSchemaTypes } from './generateSchemaTypes.js';
+import {
+  createOpenapiTypesImportPath,
+  isValidTypeScriptFileName,
+} from './lib/createOpenapiTypesImportPath.js';
+
+export const plugin: QraftCommandPlugin = {
+  setupCommand(command) {
+    command
+      .description(
+        'Generate TypeScript types from OpenAPI 3.x Document. Based on "openapi-typescript" (https://github.com/drwpow/openapi-typescript/)'
+      )
+      .option(
+        '--openapi-types-file-name <path>',
+        'OpenAPI Schema types file name, eg: "schema.d.ts"',
+        openapiTypesFileNameOptionParser,
+        'schema.ts'
+      )
+      .option('--enum', 'Export true TS enums instead of unions')
+      .option(
+        '-t, --export-type',
+        'Export top-level `type` instead of `interface`'
+      )
+      .option('--immutable', 'Generate readonly types')
+      .option(
+        '--additional-properties',
+        'Treat schema objects as if `additionalProperties: true` is set'
+      )
+      .option(
+        '--empty-objects-unknown',
+        'Generate `unknown` instead of `Record<string, never>` for empty objects'
+      )
+      .option(
+        '--default-non-nullable',
+        'Set to `false` to ignore default values when generating non-nullable types'
+      )
+      .option(
+        '--properties-required-by-default',
+        'Treat schema objects as if `required` is set to all properties by default'
+      )
+      .option(
+        '--array-length',
+        'Generate tuples using array minItems / maxItems'
+      )
+      .option(
+        '--path-params-as-types',
+        'Convert paths to template literal types'
+      )
+      .option('--alphabetize', 'Sort object keys alphabetically')
+      .option('--exclude-deprecated', 'Exclude deprecated types')
+      .option(
+        '--no-blob-from-binary',
+        'If this option is enabled, binary format fields will not be converted to Blob types, preserving the native representation'
+      )
+      .action(async ({ output, args, spinner, schema }, resolve) => {
+        spinner.text = 'Generating OpenAPI Document Types';
+
+        const code = await generateSchemaTypes(schema, {
+          args,
+          silent: true,
+        });
+
+        spinner.succeed('OpenAPI Document types generated');
+
+        resolve([
+          {
+            file: new URL(args.openapiTypesFileName, output.dir),
+            code: formatFileHeader(args.fileHeader ?? fileHeader) + code,
+          },
+        ]);
+      });
+  },
+  postSetupCommand(command, plugins) {
+    if (!plugins.includes('tanstack-query-react')) return;
+
+    // Makes `--openapi-types-import-path` option to be optional
+    command.options
+      .find((option) => option.attributeName() === 'openapiTypesImportPath')
+      ?.makeOptionMandatory(false);
+
+    // Highlight the `--export-openapi-types` option default value
+    command.options
+      .find((option) => {
+        return option.attributeName() === 'exportOpenapiTypes';
+      })
+      ?.default(true);
+
+    command.hook('preAction', (thisCommand) => {
+      // Do not override if a custom value already exists
+      if (!command.getOptionValue('openapiTypesImportPath')) {
+        thisCommand.setOptionValue(
+          'openapiTypesImportPath',
+          createOpenapiTypesImportPath(
+            thisCommand.getOptionValue('openapiTypesFileName'),
+            thisCommand.getOptionValue('explicitImportExtensions')
+          )
+        );
+      }
+
+      // If the option is not set, set it to true
+      if (command.getOptionValue('exportOpenapiTypes') === undefined) {
+        thisCommand.setOptionValue('exportOpenapiTypes', true);
+      }
+    });
+  },
+};
+
+export function openapiTypesFileNameOptionParser(value: string) {
+  if (!isValidTypeScriptFileName(value)) {
+    throw new CommanderError(
+      1,
+      'ERR_INVALID_SCHEMA_FILE_NAME',
+      'OpenAPI Schema types file name must end with ".ts" or ".d.ts"'
+    );
+  }
+
+  if (value.includes('/') || value.includes('\\')) {
+    throw new CommanderError(
+      1,
+      'ERR_INVALID_SCHEMA_FILE_NAME',
+      'OpenAPI Schema types file name must not include path'
+    );
+  }
+
+  if (value.startsWith('.')) {
+    throw new CommanderError(
+      1,
+      'ERR_INVALID_SCHEMA_FILE_NAME',
+      'OpenAPI Schema types file name must not start with "."'
+    );
+  }
+
+  return value;
+}