api-typescript-generator - npm Package Compare versions

Comparing version 2.4.16 to 2.4.17

docs/classes/openapi_client.CommonHttpClientError.md

@@ -7,2 +7,4 @@ [api-typescript-generator](../../README.md) / [Modules](../modules.md) / [openapi-client](../modules/openapi_client.md) / CommonHttpClientError
 
+Error thrown by the common HTTP client.
+
 ## Hierarchy
@@ -53,2 +55,4 @@
 
+Options of the common HTTP client.
+
 ___
@@ -60,2 +64,4 @@
 
+Request that caused the error. Can be undefined in case of failure during request building phase.
+
 ___
@@ -67,2 +73,4 @@
 
+Response that caused the error. Can be undefined in case of network failure.
+
 ___
@@ -73,1 +81,3 @@
 • `Readonly` **url**: `URL`
+
+URL of the request.

docs/interfaces/openapi_client.CommonHttpClientFetchRequestHeaders.md

@@ -7,4 +7,6 @@ [api-typescript-generator](../../README.md) / [Modules](../modules.md) / [openapi-client](../modules/openapi_client.md) / CommonHttpClientFetchRequestHeaders
 
+Request headers as used by the fetch function.
+
 ## Indexable
 
 ▪ [headerName: `string`]: `string`

docs/interfaces/openapi_client.CommonHttpClientOptions.md

@@ -7,2 +7,4 @@ [api-typescript-generator](../../README.md) / [Modules](../modules.md) / [openapi-client](../modules/openapi_client.md) / CommonHttpClientOptions
 
+Options for the common HTTP client.
+
 ## Table of contents
@@ -27,2 +29,4 @@
 
+Base URL for the API. Endpoints are relative to this URL.
+
 ___
@@ -34,2 +38,4 @@
 
+Type of the response body for binary responses.
+
 ___
@@ -45,2 +51,4 @@
 
+Error class to be thrown when an error occurs.
+
 ##### Parameters
@@ -66,2 +74,4 @@
 
+Fetch function. Default is window.fetch-based implementation.
+
 ##### Parameters
@@ -88,2 +98,4 @@
 
+Format the HTTP error message.
+
 ##### Parameters
@@ -106,2 +118,4 @@
 
+Default headers to be sent with each request.
+
 ___
@@ -117,2 +131,4 @@
 
+Preprocess the response before returning it.
+
 ##### Parameters
@@ -139,2 +155,4 @@
 
+Preprocess the request before sending it.
+
 ##### Parameters
@@ -141,0 +159,0 @@

docs/interfaces/openapi_client.CommonHttpClientRequestHeaders.md

@@ -7,4 +7,6 @@ [api-typescript-generator](../../README.md) / [Modules](../modules.md) / [openapi-client](../modules/openapi_client.md) / CommonHttpClientRequestHeaders
 
+A forgiving version of the request headers. Undefined and null values are allowed.
+
 ## Indexable
 
 ▪ [headerName: `string`]: `string` \| `undefined` \| ``null``

docs/interfaces/openapi_client.OpenApiClientGeneratorConfigCore.md

@@ -15,2 +15,3 @@ [api-typescript-generator](../../README.md) / [Modules](../modules.md) / [openapi-client](../modules/openapi_client.md) / OpenApiClientGeneratorConfigCore
 - [filenameFormat](openapi_client.OpenApiClientGeneratorConfigCore.md#filenameformat)
+- [generateJsDoc](openapi_client.OpenApiClientGeneratorConfigCore.md#generatejsdoc)
 - [relativeDirPath](openapi_client.OpenApiClientGeneratorConfigCore.md#relativedirpath)
@@ -49,2 +50,10 @@
 
+### generateJsDoc
+
+• `Optional` **generateJsDoc**: [`GenerateCoreJsDoc`](../modules/openapi_client.md#generatecorejsdoc)
+
+JSDoc generation callback for core classes / members.
+
+___
+
 ### relativeDirPath
@@ -51,0 +60,0 @@

docs/modules/openapi_client.md

@@ -41,2 +41,3 @@ [api-typescript-generator](../../README.md) / [Modules](../modules.md) / openapi-client
 - [GenerateClientJsDoc](openapi_client.md#generateclientjsdoc)
+- [GenerateCoreJsDoc](openapi_client.md#generatecorejsdoc)
 - [GenerateModelJsDoc](openapi_client.md#generatemodeljsdoc)
@@ -150,2 +151,38 @@ - [GenerateModelNameCallback](openapi_client.md#generatemodelnamecallback)
 
+### GenerateCoreJsDoc
+
+Ƭ **GenerateCoreJsDoc**: (`params`: \{ `memberName?`: `string` ; `suggestedJsDoc`: [`JsDocBlock`](../interfaces/index.JsDocBlock.md) ; `typeName`: `string`  }) => [`JsDocBlock`](../interfaces/index.JsDocBlock.md)
+
+#### Type declaration
+
+▸ (`params`): [`JsDocBlock`](../interfaces/index.JsDocBlock.md)
+
+Callback for generating the JSDoc for core classes.
+
+##### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `params` | `Object` | - |
+| `params.memberName?` | `string` | Name of the member of the core class. Empty if the JSDoc is for the class itself. |
+| `params.suggestedJsDoc` | [`JsDocBlock`](../interfaces/index.JsDocBlock.md) | Suggested JSDoc block. Used by default if the callback is not specified. |
+| `params.typeName` | `string` | Name of the core class. |
+
+##### Returns
+
+[`JsDocBlock`](../interfaces/index.JsDocBlock.md)
+
+**`Example`**
+
+```ts
+function GenerateCoreJsDoc({suggestedJsDoc}) {
+        return {
+            ...suggestedJsDoc,
+            tags: [...suggestedJsDoc.tags, {name: 'internal'}]
+        };
+    }
+```
+
+___
+
 ### GenerateModelJsDoc
@@ -152,0 +189,0 @@

lib/openapi-client.d.ts

@@ -1,2 +0,2 @@
-export type { OpenApiClientGeneratorConfig, GenerateModelJsDoc, GenerateModelNameCallback, GenerateOperationJsDoc, GenerateOperationName, GenerateOperationParameterArgumentName, GenerateOperationParameterJsDoc, GenerateOperationRequestBodyJsDoc, GenerateServiceName, GenerateOperationRequestBodyArgumentName, GenerateOperationResultDescription, GenerateServiceJsDoc, GenerateClientJsDoc, GenerateClientErrorJsDoc, OpenApiClientBuiltinBinaryType, OpenApiClientCustomizableBinaryType, OpenApiClientExternalType, OpenApiClientExternalValue, OpenApiClientExternalValueSource, OpenApiClientGeneratorConfigOperations, OpenApiClientGeneratorConfigClient, OpenApiClientGeneratorConfigModels, OpenApiClientGeneratorConfigServices, OpenApiClientGeneratorConfigCore, OpenApiClientGeneratorConfigValidation, OpenApiClientGeneratorConfigComments, OpenApiClientGeneratorConfigJsDoc, OpenApiClientGeneratorConfigJsDocWordWrap, OpenApiClientGeneratorConfigValidationSchemaStorage, OpenApiClientExternalValueSourceImportEntity } from './schema-to-typescript/openapi-to-typescript-client';
+export type { OpenApiClientGeneratorConfig, GenerateModelJsDoc, GenerateModelNameCallback, GenerateOperationJsDoc, GenerateOperationName, GenerateOperationParameterArgumentName, GenerateOperationParameterJsDoc, GenerateOperationRequestBodyJsDoc, GenerateServiceName, GenerateOperationRequestBodyArgumentName, GenerateOperationResultDescription, GenerateServiceJsDoc, GenerateClientJsDoc, GenerateClientErrorJsDoc, GenerateCoreJsDoc, OpenApiClientBuiltinBinaryType, OpenApiClientCustomizableBinaryType, OpenApiClientExternalType, OpenApiClientExternalValue, OpenApiClientExternalValueSource, OpenApiClientGeneratorConfigOperations, OpenApiClientGeneratorConfigClient, OpenApiClientGeneratorConfigModels, OpenApiClientGeneratorConfigServices, OpenApiClientGeneratorConfigCore, OpenApiClientGeneratorConfigValidation, OpenApiClientGeneratorConfigComments, OpenApiClientGeneratorConfigJsDoc, OpenApiClientGeneratorConfigJsDocWordWrap, OpenApiClientGeneratorConfigValidationSchemaStorage, OpenApiClientExternalValueSourceImportEntity } from './schema-to-typescript/openapi-to-typescript-client';
 export type { CommonHttpClientFetchRequest, CommonHttpClientFetchResponse, CommonHttpClientError, CommonHttpClientRequest, CommonHttpClientResponse, CommonHttpClientFetchResponseBody, CommonHttpClientFetchRequestHeaders, CommonHttpClientResponseHeaders, CommonHttpClientOptions, CommonHttpClientRequestHeaders } from './schema-to-typescript/common/core/common-http-client';

lib/schema-to-typescript/common/client-core.d.ts

 import { CommentsRenderConfig } from '../common';
 import { ClientGenerationResultFile } from '../config';
 export declare const defaultCoreRelativeDirPath = "core";
-export declare function generateCommonHttpClient({ filenameFormat, relativeDirPath }: import("../openapi-to-typescript-client").OpenApiClientGeneratorConfigCore | undefined, commentsConfig: CommentsRenderConfig): Promise<{
+export declare function generateCommonHttpClient({ filenameFormat, relativeDirPath, generateJsDoc }: import("../openapi-to-typescript-client").OpenApiClientGeneratorConfigCore | undefined, commentsConfig: CommentsRenderConfig): Promise<{
     importPath: string;
@@ -11,3 +11,3 @@ className: string;
 }>;
-export declare function generateCommonHttpService({ filenameFormat, relativeDirPath }: import("../openapi-to-typescript-client").OpenApiClientGeneratorConfigCore | undefined, commentsConfig: CommentsRenderConfig): Promise<{
+export declare function generateCommonHttpService({ filenameFormat, relativeDirPath, generateJsDoc }: import("../openapi-to-typescript-client").OpenApiClientGeneratorConfigCore | undefined, commentsConfig: CommentsRenderConfig): Promise<{
     importPath: string;
@@ -17,3 +17,3 @@ className: string;
 }>;
-export declare function generateCommonValidationSchemaStorage({ filenameFormat, relativeDirPath }: import("../openapi-to-typescript-client").OpenApiClientGeneratorConfigCore | undefined, commentsConfig: CommentsRenderConfig): Promise<{
+export declare function generateCommonValidationSchemaStorage({ filenameFormat, relativeDirPath, generateJsDoc }: import("../openapi-to-typescript-client").OpenApiClientGeneratorConfigCore | undefined, commentsConfig: CommentsRenderConfig): Promise<{
     importPath: string;
@@ -20,0 +20,0 @@ className: string;

lib/schema-to-typescript/common/client-core.js

@@ -19,12 +19,69 @@ "use strict";
 const parser_1 = require("@babel/parser");
+const traverse_1 = __importDefault(require("@babel/traverse"));
+const types_1 = require("@babel/types");
+const jsdoc_1 = require("../../utils/jsdoc");
 const string_utils_1 = require("../../utils/string-utils");
 const common_1 = require("../common");
-function processCoreFile(code, filenameFormat, commentsConfig) {
-    return (0, common_1.renderTypeScript)((0, parser_1.parse)(code.replace(/import([\s\S]*?)from '.\/([^']+)';/g, (_, imports, path) => `import${imports}from ${JSON.stringify(`./${(0, string_utils_1.formatFilename)(path, filenameFormat)}`)};`), {
+function updateJsDoc({ typeName, memberName, node, generateJsDoc }) {
+    var _a;
+    const jsDocComment = (_a = node.leadingComments) === null || _a === void 0 ? void 0 : _a.find(jsdoc_1.isJsDocComment);
+    (0, jsdoc_1.attachJsDocComment)(node, (0, jsdoc_1.renderJsDoc)(generateJsDoc({
+        typeName,
+        memberName,
+        suggestedJsDoc: jsDocComment ? (0, jsdoc_1.parseJsDoc)(jsDocComment.value) : { tags: [] }
+    })));
+}
+function removeTrailingComments(parseResult) {
+    (0, traverse_1.default)(parseResult, {
+        exit(path) {
+            if (path.node.trailingComments) {
+                path.node.trailingComments = [];
+            }
+        }
+    });
+}
+function processCoreFile(code, filenameFormat, commentsConfig, generateJsDoc) {
+    var _a, _b;
+    const parseResult = (0, parser_1.parse)(code, {
         sourceType: 'module',
         plugins: ['typescript']
-    }).program, commentsConfig);
+    });
+    removeTrailingComments(parseResult);
+    const program = parseResult.program;
+    for (const statement of program.body) {
+        if ((0, types_1.isImportDeclaration)(statement)) {
+            if (!statement.source.value.startsWith('./')) {
+                throw new Error(`Unexpected import path: ${statement.source.value}`);
+            }
+            statement.source.value = `./${(0, string_utils_1.formatFilename)(statement.source.value.slice(2), filenameFormat)}`;
+        }
+        if (generateJsDoc) {
+            if ((0, types_1.isExportNamedDeclaration)(statement)) {
+                if ((0, types_1.isClassDeclaration)(statement.declaration)) {
+                    const classDeclaration = statement.declaration;
+                    if (!((_a = classDeclaration.id) === null || _a === void 0 ? void 0 : _a.name)) {
+                        throw new Error('Unexpected class declaration without name.');
+                    }
+                    updateJsDoc({ node: statement, typeName: (_b = classDeclaration.id) === null || _b === void 0 ? void 0 : _b.name, generateJsDoc });
+                    for (const member of classDeclaration.body.body) {
+                        if ((0, types_1.isClassMethod)(member) || (0, types_1.isClassProperty)(member) || (0, types_1.isClassAccessorProperty)(member)) {
+                            if (!(0, types_1.isIdentifier)(member.key)) {
+                                throw new Error('Unexpected member without key.');
+                            }
+                            updateJsDoc({
+                                node: member,
+                                typeName: classDeclaration.id.name,
+                                memberName: member.key.name,
+                                generateJsDoc
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return (0, common_1.renderTypeScript)(JSON.parse(JSON.stringify(program)), commentsConfig);
 }
 exports.defaultCoreRelativeDirPath = 'core';
-function generateCommonHttpClient({ filenameFormat, relativeDirPath = exports.defaultCoreRelativeDirPath } = {}, commentsConfig) {
+function generateCommonHttpClient({ filenameFormat, relativeDirPath = exports.defaultCoreRelativeDirPath, generateJsDoc } = {}, commentsConfig) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -38,3 +95,3 @@ return {
                 filename: path_1.default.join(relativeDirPath, (0, string_utils_1.formatFilename)('common-http-client', Object.assign(Object.assign({}, filenameFormat), { extension: '.ts' }))),
-                data: processCoreFile(yield fs_1.default.promises.readFile(path_1.default.join(__dirname, 'core', 'common-http-client.ts'), 'utf8'), filenameFormat, commentsConfig)
+                data: processCoreFile(yield fs_1.default.promises.readFile(path_1.default.join(__dirname, 'core', 'common-http-client.ts'), 'utf8'), filenameFormat, commentsConfig, generateJsDoc)
             }
@@ -45,3 +102,3 @@ };
 exports.generateCommonHttpClient = generateCommonHttpClient;
-function generateCommonHttpService({ filenameFormat, relativeDirPath = exports.defaultCoreRelativeDirPath } = {}, commentsConfig) {
+function generateCommonHttpService({ filenameFormat, relativeDirPath = exports.defaultCoreRelativeDirPath, generateJsDoc } = {}, commentsConfig) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -53,3 +110,3 @@ return {
                 filename: path_1.default.join(relativeDirPath, `${(0, string_utils_1.formatFilename)('common-http-service', Object.assign(Object.assign({}, filenameFormat), { extension: '.ts' }))}`),
-                data: processCoreFile(yield fs_1.default.promises.readFile(path_1.default.join(__dirname, 'core', 'common-http-service.ts'), 'utf8'), filenameFormat, commentsConfig)
+                data: processCoreFile(yield fs_1.default.promises.readFile(path_1.default.join(__dirname, 'core', 'common-http-service.ts'), 'utf8'), filenameFormat, commentsConfig, generateJsDoc)
             }
@@ -60,3 +117,3 @@ };
 exports.generateCommonHttpService = generateCommonHttpService;
-function generateCommonValidationSchemaStorage({ filenameFormat, relativeDirPath = exports.defaultCoreRelativeDirPath } = {}, commentsConfig) {
+function generateCommonValidationSchemaStorage({ filenameFormat, relativeDirPath = exports.defaultCoreRelativeDirPath, generateJsDoc } = {}, commentsConfig) {
     return __awaiter(this, void 0, void 0, function* () {
@@ -68,3 +125,3 @@ return {
                 filename: path_1.default.join(relativeDirPath, `${(0, string_utils_1.formatFilename)('common-validation-schema-storage', Object.assign(Object.assign({}, filenameFormat), { extension: '.ts' }))}`),
-                data: processCoreFile(yield fs_1.default.promises.readFile(path_1.default.join(__dirname, 'core', 'common-validation-schema-storage.ts'), 'utf8'), filenameFormat, commentsConfig)
+                data: processCoreFile(yield fs_1.default.promises.readFile(path_1.default.join(__dirname, 'core', 'common-validation-schema-storage.ts'), 'utf8'), filenameFormat, commentsConfig, generateJsDoc)
             }
@@ -71,0 +128,0 @@ };

lib/schema-to-typescript/common/core/common-http-client.d.ts

@@ -13,8 +13,8 @@ export interface CommonHttpClientOptions {
 }
+export interface CommonHttpClientFetchRequestHeaders {
+    [headerName: string]: string;
+}
 export interface CommonHttpClientRequestHeaders {
     [headerName: string]: string | undefined | null;
 }
-export interface CommonHttpClientFetchRequestHeaders {
-    [headerName: string]: string;
-}
 export interface CommonHttpClientFetchRequest {
@@ -21,0 +21,0 @@ method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'PATCH';

lib/schema-to-typescript/common/core/common-http-client.ts

@@ -0,3 +1,12 @@
+/**
+ * Options for the common HTTP client.
+ */
 export interface CommonHttpClientOptions {
+    /**
+     * Base URL for the API. Endpoints are relative to this URL.
+     */
     baseUrl: string;
+    /**
+     * Error class to be thrown when an error occurs.
+     */
     errorClass: {
@@ -12,4 +21,13 @@ new (
     };
+    /**
+     * Default headers to be sent with each request.
+     */
     headers?: CommonHttpClientRequestHeaders;
+    /**
+     * Preprocess the request before sending it.
+     */
     preprocessRequest?: (request: CommonHttpClientRequest) => Promise<CommonHttpClientRequest>;
+    /**
+     * Preprocess the response before returning it.
+     */
     preprocessFetchResponse?: (
@@ -19,11 +37,19 @@ response: CommonHttpClientFetchResponse,
     ) => Promise<CommonHttpClientFetchResponse>;
+    /**
+     * Fetch function. Default is window.fetch-based implementation.
+     */
     fetch?: (url: URL, request: CommonHttpClientFetchRequest) => Promise<CommonHttpClientFetchResponse>;
+    /**
+     * Type of the response body for binary responses.
+     */
     binaryResponseType: 'blob' | 'readableStream';
+    /**
+     * Format the HTTP error message.
+     */
     formatHttpErrorMessage?: (response: CommonHttpClientFetchResponse, request: CommonHttpClientFetchRequest) => string;
 }
 
-export interface CommonHttpClientRequestHeaders {
-    [headerName: string]: string | undefined | null;
-}
-
+/**
+ * Request headers as used by the fetch function.
+ */
 export interface CommonHttpClientFetchRequestHeaders {
@@ -34,2 +60,9 @@ [headerName: string]: string;
 /**
+ * A forgiving version of the request headers. Undefined and null values are allowed.
+ */
+export interface CommonHttpClientRequestHeaders {
+    [headerName: string]: string | undefined | null;
+}
+
+/**
  * Request prepared for the fetch function.
@@ -147,6 +180,21 @@ */
 
+/**
+ * Error thrown by the common HTTP client.
+ */
 export class CommonHttpClientError extends Error {
+    /**
+     * URL of the request.
+     */
     public readonly url: URL;
+    /**
+     * Request that caused the error. Can be undefined in case of failure during request building phase.
+     */
     public readonly request: CommonHttpClientFetchRequest | undefined;
+    /**
+     * Response that caused the error. Can be undefined in case of network failure.
+     */
     public readonly response: CommonHttpClientFetchResponse | undefined;
+    /**
+     * Options of the common HTTP client.
+     */
     public readonly options: CommonHttpClientOptions | undefined;
@@ -188,2 +236,5 @@ constructor(
 
+/**
+ * Convert the response body to the desired type.
+ */
 async function convertResponseBody(
@@ -323,2 +374,5 @@ body: CommonHttpClientFetchResponseBody,
 
+/**
+ * Common HTTP client. Configurable for different environments.
+ */
 export class CommonHttpClient {
@@ -331,2 +385,5 @@ protected options: CommonHttpClientOptions;
 
+    /**
+     * Configure the client.
+     */
     public setOptions(options: CommonHttpClientOptions) {
@@ -336,2 +393,5 @@ this.options = options;
 
+    /**
+     * Get the current configuration.
+     */
     public getOptions(): CommonHttpClientOptions {
@@ -341,2 +401,5 @@ return this.options;
 
+    /**
+     * Turns an object with query params into a URLSearchParams object.
+     */
     protected getSearchParams(params: Record<string, unknown>): URLSearchParams {
@@ -368,2 +431,5 @@ const result = new URLSearchParams();
 
+    /**
+     * Build the URL path from the request by applying path params.
+     */
     protected buildUrlPath(request: CommonHttpClientRequest): string {
@@ -382,2 +448,5 @@ const pathParams = request.pathParams;
 
+    /**
+     * Build the full URL from the request.
+     */
     protected buildUrl(request: CommonHttpClientRequest): URL {
@@ -393,2 +462,5 @@ const url = new URL(this.buildUrlPath(request).replace(/^\//, ''), this.options.baseUrl.replace(/\/?$/, '/'));
 
+    /**
+     * Default fetch implementation.
+     */
     protected async fetch(url: URL, request: CommonHttpClientFetchRequest): Promise<CommonHttpClientFetchResponse> {
@@ -419,2 +491,5 @@ const {...requestProps} = request;
 
+    /**
+     * Perform a request.
+     */
     public async request(request: CommonHttpClientRequest): Promise<CommonHttpClientFetchResponse> {
@@ -513,2 +588,5 @@ try {
 
+    /**
+     * Post-process the response.
+     */
     responseHandler(distribution: {
@@ -582,2 +660,5 @@ [statusCode: string]: {[mediaType: string]: CommonHttpClientFetchResponseBody['type']};
 
+    /**
+     * Remove undefined and null values from headers.
+     */
     private cleanupHeaders(headers?: CommonHttpClientRequestHeaders): CommonHttpClientFetchRequestHeaders {
@@ -584,0 +665,0 @@ if (headers === undefined) {

lib/schema-to-typescript/common/core/common-http-service.ts

 import * as commonHttpClient from './common-http-client';
 
+/**
+ * Base class for all services that need to make HTTP requests.
+ */
 export class CommonHttpService {
+    /**
+     * Map of child service instances to avoid creating multiple instances of the same service.
+     */
     protected serviceInstancesMap: Map<
@@ -9,2 +15,5 @@ new (getClientInstance: () => commonHttpClient.CommonHttpClient) => CommonHttpService,
 
+    /**
+     * Get an instance of the specified service class.
+     */
     protected getServiceInstance<T extends CommonHttpService>(
@@ -21,3 +30,10 @@ serviceClass: new (getClientInstance: () => commonHttpClient.CommonHttpClient) => T
 
+    /**
+     * Get an instance of the HTTP client.
+     */
     protected getClientInstance: () => commonHttpClient.CommonHttpClient;
+
+    /**
+     * Create a new instance of the service.
+     */
     constructor(getClientInstance: () => commonHttpClient.CommonHttpClient) {
@@ -36,4 +52,12 @@ this.getClientInstance = () => {
     }
+
+    /**
+     * Flag to indicate if the class has been initialized to avoid multiple initializations.
+     */
     protected static initialized: boolean | undefined;
+
+    /**
+     * Method to initialize the class. Normally used to set up validation rules.
+     */
     protected static initialize: (() => void) | undefined;
 }

lib/schema-to-typescript/openapi-to-typescript-client.d.ts

@@ -104,2 +104,7 @@ import { ValidationProvider } from './common/validation-providers/validation-provider';
 }) => JsDocBlock;
+export type GenerateCoreJsDoc = (params: {
+    suggestedJsDoc: JsDocBlock;
+    typeName: string;
+    memberName?: string;
+}) => JsDocBlock;
 export type OpenApiClientExternalValueSourceImportEntity = {
@@ -174,2 +179,3 @@ name: string;
     cleanupFiles?: boolean;
+    generateJsDoc?: GenerateCoreJsDoc;
 }
@@ -176,0 +182,0 @@ export interface OpenApiClientGeneratorConfigValidationSchemaStorage {

lib/utils/jsdoc.d.ts

@@ -1,2 +0,2 @@
-import { Node } from '@babel/types';
+import { Node, Comment } from '@babel/types';
 import { AnnotatedApiEntity } from '../schema-to-typescript/common';
@@ -20,1 +20,3 @@ import { OpenApiClientGeneratorConfig } from '../schema-to-typescript/openapi-to-typescript-client';
 export declare function extractJsDocString(entity: AnnotatedApiEntity | boolean, params?: JsDocBlockTag[]): string | null;
+export declare function isJsDocComment(node: Comment): boolean;
+export declare function parseJsDoc(comment: string): JsDocBlock;

lib/utils/jsdoc.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractJsDocString = exports.attachJsDocComment = exports.renderJsDoc = exports.renderJsDocAsPlainText = exports.renderJsDocList = exports.extractJsDoc = void 0;
+exports.parseJsDoc = exports.isJsDocComment = exports.extractJsDocString = exports.attachJsDocComment = exports.renderJsDoc = exports.renderJsDocAsPlainText = exports.renderJsDocList = exports.extractJsDoc = void 0;
 const types_1 = require("@babel/types");
@@ -140,10 +140,13 @@ const string_utils_1 = require("./string-utils");
     if (jsdoc) {
+        (0, types_1.removeComments)(node);
         if (!jsdoc.match(/\n/)) {
             (0, types_1.addComment)(node, 'leading', `* ${jsdoc.replace(/\*\//g, '* /')} `, false);
-            node.leadingComments[0].loc = {
-                filename: '',
-                identifierName: undefined,
-                start: { line: 0, column: 0, index: 0 },
-                end: { line: 1, column: 1, index: 1 }
-            };
+            if ((0, types_1.isTSPropertySignature)(node)) {
+                node.leadingComments[0].loc = {
+                    filename: '',
+                    identifierName: undefined,
+                    start: { line: 0, column: 0, index: 0 },
+                    end: { line: 1, column: 1, index: 1 }
+                };
+            }
         }
@@ -163,1 +166,54 @@ else {
 exports.extractJsDocString = extractJsDocString;
+function isJsDocComment(node) {
+    return node.type === 'CommentBlock' && node.value.startsWith('*');
+}
+exports.isJsDocComment = isJsDocComment;
+function parseJsDoc(comment) {
+    const lines = comment
+        .replace(/(?:\r\n|\r|\n|^)\s*\* ?/g, '\n')
+        .trim()
+        .split(/\n/);
+    const result = { tags: [] };
+    while (lines.length > 0) {
+        const line = lines[0];
+        if (!line.trim() && result.title) {
+            break;
+        }
+        if (line.startsWith('@')) {
+            break;
+        }
+        result.title = result.title ? `${result.title}\n${line}` : line;
+        lines.shift();
+    }
+    while (lines.length > 0) {
+        const line = lines[0];
+        if (line.startsWith('@')) {
+            break;
+        }
+        result.description = result.description ? `${result.description}\n${line}` : line;
+        lines.shift();
+    }
+    let currentTag = null;
+    while (lines.length > 0) {
+        const line = lines.shift();
+        const match = line.match(/^@(\S+)\s*(.*)?$/);
+        if (match) {
+            const name = match[1];
+            const value = match[2] && match[2].trim();
+            currentTag = {
+                name,
+                value: value || undefined
+            };
+            result.tags.push(currentTag);
+        }
+        else if (currentTag) {
+            currentTag.value = currentTag.value ? `${currentTag.value}\n${line}` : line;
+        }
+        else {
+            throw new Error(`Unexpected JsDoc tag: ${line}`);
+        }
+        lines.shift();
+    }
+    return result;
+}
+exports.parseJsDoc = parseJsDoc;

package.json

 {
   "name": "api-typescript-generator",
-  "version": "2.4.16",
+  "version": "2.4.17",
   "description": "Generates OpenAPI TypeScript client. Extremely fast and flexible.",
@@ -81,3 +81,4 @@ "license": "MIT",
     "@babel/parser": "^7.24.4",
-    "@babel/types": "^7.15.4",
+    "@babel/types": "^7.24.4",
+    "@babel/traverse": "^7.24.4",
     "js-yaml": "^4.1.0",
@@ -84,0 +85,0 @@ "ramda": "^0.27.1",

No alert changes

Improved metrics

Total package byte prevSize

440876

increased by2.22%

Lines of code

6136

increased by3.77%

Worsened metrics

Dependency count

9

increased by12.5%

Dependency changes

• + Added@babel/traverse@^7.24.4

• + Added@babel/code-frame@7.26.2(transitive)

• + Added@babel/template@7.25.9(transitive)

• + Added@babel/traverse@7.26.7(transitive)

• + Addeddebug@4.4.0(transitive)

• + Addedglobals@11.12.0(transitive)

• + Addedjs-tokens@4.0.0(transitive)

• + Addedms@2.1.3(transitive)

• + Addedpicocolors@1.1.1(transitive)

• Updated@babel/types@^7.24.4