feat: ability to show warnings in case of deprecated operation calls

Author: mdevils

docs/interfaces/openapi_client.CommonHttpClientOptions.md

@@ -12,6 +12,7 @@ Options for the common HTTP client.
 
 - [baseUrl](openapi_client.CommonHttpClientOptions.md#baseurl)
 - [binaryResponseType](openapi_client.CommonHttpClientOptions.md#binaryresponsetype)
+- [deprecatedOperations](openapi_client.CommonHttpClientOptions.md#deprecatedoperations)
 - [errorClass](openapi_client.CommonHttpClientOptions.md#errorclass)
 - [fetch](openapi_client.CommonHttpClientOptions.md#fetch)
 - [formatHttpErrorMessage](openapi_client.CommonHttpClientOptions.md#formathttperrormessage)
@@ -20,6 +21,10 @@ Options for the common HTTP client.
 - [preprocessFetchResponse](openapi_client.CommonHttpClientOptions.md#preprocessfetchresponse)
 - [preprocessRequest](openapi_client.CommonHttpClientOptions.md#preprocessrequest)
 
+### Methods
+
+- [logDeprecationWarning](openapi_client.CommonHttpClientOptions.md#logdeprecationwarning)
+
 ## Properties
 
 ### baseUrl
@@ -38,6 +43,18 @@ Type of the response body for binary responses.
 
 ___
 
+### deprecatedOperations
+
+• `Optional` **deprecatedOperations**: `Object`
+
+Deprecated operations. Used to warn about deprecated operations.
+
+#### Index signature
+
+▪ [methodAndPath: `string`]: `string`
+
+___
+
 ### errorClass
 
 • **errorClass**: (`url`: `URL`, `request`: `undefined` \| [`CommonHttpClientFetchRequest`](openapi_client.CommonHttpClientFetchRequest.md), `response`: `undefined` \| [`CommonHttpClientFetchResponse`](openapi_client.CommonHttpClientFetchResponse.md), `options`: `undefined` \| [`CommonHttpClientOptions`](openapi_client.CommonHttpClientOptions.md), `message`: `string`) => `Error`
@@ -178,3 +195,24 @@ Preprocess the request before sending it.
 ##### Returns
 
 `Promise`\<[`CommonHttpClientRequest`](../modules/openapi_client.md#commonhttpclientrequest)\>
+
+## Methods
+
+### logDeprecationWarning
+
+▸ `Optional` **logDeprecationWarning**(`params`): `void`
+
+Log a deprecation warning.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `params` | `Object` | - |
+| `params.method` | ``"GET"`` \| ``"HEAD"`` \| ``"POST"`` \| ``"PUT"`` \| ``"DELETE"`` \| ``"CONNECT"`` \| ``"OPTIONS"`` \| ``"PATCH"`` | - |
+| `params.operationName` | `string` | Either operation method name in case if it's not part of the service, or service name and operation method name separated by a dot. Examples: `users.getUserById`, `getSystemConfig` |
+| `params.path` | `string` | - |
+
+#### Returns
+
+`void`

docs/interfaces/openapi_client.OpenApiClientGeneratorConfigOperations.md

@@ -20,6 +20,7 @@ Configuration for generating operation calls.
 - [makeResponseValidationSchemasExtensible](openapi_client.OpenApiClientGeneratorConfigOperations.md#makeresponsevalidationschemasextensible)
 - [mediaTypeArgumentName](openapi_client.OpenApiClientGeneratorConfigOperations.md#mediatypeargumentname)
 - [responseBinaryType](openapi_client.OpenApiClientGeneratorConfigOperations.md#responsebinarytype)
+- [showDeprecatedWarnings](openapi_client.OpenApiClientGeneratorConfigOperations.md#showdeprecatedwarnings)
 - [validateResponse](openapi_client.OpenApiClientGeneratorConfigOperations.md#validateresponse)
 
 ## Properties
@@ -123,6 +124,20 @@ Binary response/request type. Used when the response is not a JSON value.
 
 ___
 
+### showDeprecatedWarnings
+
+• `Optional` **showDeprecatedWarnings**: `boolean`
+
+Shows a warning when a deprecated operation is used.
+
+**`Default`**
+
+```ts
+false
+```
+
+___
+
 ### validateResponse
 
 • `Optional` **validateResponse**: `boolean`

src/schema-to-typescript/common/client.ts

@@ -111,7 +111,8 @@ export function generateClient({
     responseBinaryType,
     binaryTypes,
     jsDocRenderConfig,
-    commentsConfig
+    commentsConfig,
+    deprecatedOperations
 }: {
     commonHttpClientClassName: string;
     commonHttpClientClassOptionsName: string;
@@ -132,6 +133,7 @@ export function generateClient({
     binaryTypes: OpenApiClientCustomizableBinaryType[];
     jsDocRenderConfig: JsDocRenderConfig;
     commentsConfig: CommentsRenderConfig;
+    deprecatedOperations: {[methodAndPath: string]: string};
 }): ClientGenerationResultFile {
     const clientPropertyName = 'client';
     const commonHttpClientImportName = 'commonHttpClient';
@@ -156,22 +158,48 @@ export function generateClient({
         )
     );
 
+    const generatedMethods = generateOperationMethods({
+        paths,
+        commonHttpClientImportName,
+        operationImportPath: clientImportPath,
+        operationsConfig,
+        getModelData,
+        validationContext,
+        binaryTypes,
+        jsDocRenderConfig
+    });
+
+    const clientConstructorOptionsObject = objectExpression([
+        objectProperty(identifier('baseUrl'), stringLiteral(baseUrl ?? servers[0]?.url ?? defaultServerUrl)),
+        objectProperty(identifier('binaryResponseType'), stringLiteral(responseBinaryType)),
+        objectProperty(identifier('errorClass'), identifier(errorTypeName))
+    ]);
+
+    const deprecatedOperationsTotal = {
+        ...deprecatedOperations,
+        ...generatedMethods.deprecatedOperations
+    };
+
+    if (operationsConfig?.showDeprecatedWarnings && Object.keys(deprecatedOperationsTotal).length > 0) {
+        clientConstructorOptionsObject.properties.push(
+            objectProperty(
+                identifier('deprecatedOperations'),
+                objectExpression(
+                    Object.entries(deprecatedOperationsTotal).map(([methodAndPath, operationName]) =>
+                        objectProperty(stringLiteral(methodAndPath), stringLiteral(operationName))
+                    )
+                )
+            )
+        );
+    }
+
     const clientClassBody = classBody([
         makeProtected(
             classProperty(
                 identifier(clientPropertyName),
                 newExpression(
                     memberExpression(identifier(commonHttpClientImportName), identifier(commonHttpClientClassName)),
-                    [
-                        objectExpression([
-                            objectProperty(
-                                identifier('baseUrl'),
-                                stringLiteral(baseUrl ?? servers[0]?.url ?? defaultServerUrl)
-                            ),
-                            objectProperty(identifier('binaryResponseType'), stringLiteral(responseBinaryType)),
-                            objectProperty(identifier('errorClass'), identifier(errorTypeName))
-                        ])
-                    ]
+                    [clientConstructorOptionsObject]
                 )
             )
         ),
@@ -242,16 +270,6 @@ export function generateClient({
     const optionsTypeStatement =
         exportOptionsType === false ? optionsTypeDeclaration : exportNamedDeclaration(optionsTypeDeclaration);
 
-    const generatedMethods = generateOperationMethods({
-        paths,
-        commonHttpClientImportName,
-        operationImportPath: clientImportPath,
-        operationsConfig,
-        getModelData,
-        validationContext,
-        binaryTypes,
-        jsDocRenderConfig
-    });
     clientClassBody.body.push(...generatedMethods.methods);
     extendDependencyImports(dependencyImports, generatedMethods.dependencyImports);
     clientClassBody.body.push(

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

@@ -49,6 +49,24 @@ export interface CommonHttpClientOptions {
      * Custom validation error handling. Can be used to log errors.
      */
     handleValidationError?: (error: Error) => void;
+    /**
+     * Deprecated operations. Used to warn about deprecated operations.
+     */
+    deprecatedOperations?: {[methodAndPath: string]: string /* Operation name */};
+    /**
+     * Log a deprecation warning.
+     */
+    logDeprecationWarning?(params: {
+        /**
+         * Either operation method name in case if it's not part of the service, or service name and operation method
+         * name separated by a dot.
+         *
+         * Examples: `users.getUserById`, `getSystemConfig`
+         */
+        operationName: string;
+        path: string;
+        method: CommonHttpClientFetchRequest['method'];
+    }): void;
 }
 
 /**
@@ -603,6 +621,12 @@ const formatParameter: Record<CommonHttpClientRequestParameterSerializeStyle, Pa
     }
 };
 
+/**
+ * Stores the deprecation warning state. For every shown deprecation warning, the method and path are stored in order to
+ * avoid showing the same warning appearing multiple times.
+ */
+const deprecationWarningShown: {[methodAndPath: string]: boolean} = {};
+
 /**
  * Common HTTP client. Configurable for different environments.
  */
@@ -627,6 +651,27 @@ export class CommonHttpClient {
         return this.options;
     }
 
+    /**
+     * Logs a deprecation warning if the operation is deprecated.
+     */
+    protected logDeprecationWarningIfNecessary(params: {path: string; method: CommonHttpClientFetchRequest['method']}) {
+        const methodAndPath = `${params.method} ${params.path}`;
+        const operationName = this.options.deprecatedOperations?.[methodAndPath];
+        if (!operationName) {
+            return;
+        }
+        if (!deprecationWarningShown[methodAndPath]) {
+            deprecationWarningShown[methodAndPath] = true;
+            if (this.options.logDeprecationWarning) {
+                this.options.logDeprecationWarning({method: params.method, path: params.path, operationName});
+            } else {
+                console.warn(
+                    `Deprecated API call ${this.constructor.name ?? 'ApiClient'}.${operationName}: ${methodAndPath}`
+                );
+            }
+        }
+    }
+
     /**
      * Turns an object with query params into a URLSearchParams object.
      */
@@ -720,6 +765,7 @@ export class CommonHttpClient {
      * Perform a request.
      */
     public async request(request: CommonHttpClientRequest): Promise<CommonHttpClientFetchResponse> {
+        this.logDeprecationWarningIfNecessary(request);
         try {
             request = await this.preprocessRequest(request);
         } catch (e) {

src/schema-to-typescript/common/operation-methods.ts

@@ -170,6 +170,7 @@ export function generateOperationMethods({
     const modelRegisterValidationSchemaImports: Record<string, true> = {};
     const methodProperties: ClassProperty[] = [];
     const validationStatements: Statement[] = [];
+    const deprecatedOperations: {[methodAndPath: string]: string} = {};
 
     if (validateResponse && !validationContext) {
         throw new Error('Validation should be configured for response validation.');
@@ -211,6 +212,9 @@ export function generateOperationMethods({
                       httpMethod
                   })
                 : suggestedOperationMethodName;
+            if (operation.deprecated) {
+                deprecatedOperations[`${httpMethod.toUpperCase()} ${path}`] = operationName;
+            }
             const operationReturn = getOperationReturnType({
                 operation,
                 getModelData,
@@ -679,5 +683,5 @@ export function generateOperationMethods({
 
     methodProperties.sort((a, b) => (a.key as Identifier).name.localeCompare((b.key as Identifier).name));
 
-    return {methods: methodProperties, dependencyImports, validationStatements};
+    return {methods: methodProperties, dependencyImports, validationStatements, deprecatedOperations};
 }

src/schema-to-typescript/common/services.ts

@@ -46,6 +46,7 @@ export interface GeneratedServicesImportInfo {
 export interface GeneratedServices {
     files: ClientGenerationResultFile[];
     services: GeneratedServicesImportInfo[];
+    deprecatedOperations: {[methodAndPath: string]: string};
 }
 
 export const defaultServicesRelativeDirPath = 'services';
@@ -87,6 +88,7 @@ export function generateServices({
     const commonHttpClientImportName = 'commonHttpClient';
     const files: ClientGenerationResultFile[] = [];
     const services: GeneratedServicesImportInfo[] = [];
+    const deprecatedOperations: {[methodAndPath: string]: string} = {};
     for (const [tag, paths] of Object.entries(taggedPaths)) {
         const importPath = path.join(
             relativeDirPath,
@@ -123,7 +125,7 @@ export function generateServices({
 
         services.push({
             name: serviceName,
-            tag: tag,
+            tag,
             importPath,
             jsdoc
         });
@@ -141,6 +143,16 @@ export function generateServices({
         });
         const serviceClassBody = classBody([...serviceMethods.methods]);
 
+        Object.assign(
+            deprecatedOperations,
+            Object.fromEntries(
+                Object.entries(serviceMethods.deprecatedOperations).map(([methodAndPath, operationName]) => [
+                    methodAndPath,
+                    `${applyEntityNameCase(tag, 'camelCase')}.${operationName}`
+                ])
+            )
+        );
+
         if (serviceMethods.validationStatements.length > 0) {
             serviceClassBody.body.push(
                 makeProtected(
@@ -186,5 +198,5 @@ export function generateServices({
             )
         });
     }
-    return {files, services};
+    return {files, services, deprecatedOperations};
 }

src/schema-to-typescript/openapi-to-typescript-client.ts

@@ -685,6 +685,12 @@ export interface OpenApiClientGeneratorConfigOperations {
      * @default 'blob'
      */
     responseBinaryType?: OpenApiClientBuiltinBinaryType;
+    /**
+     * Shows a warning when a deprecated operation is used.
+     *
+     * @default false
+     */
+    showDeprecatedWarnings?: boolean;
 }
 
 /**
@@ -1125,7 +1131,7 @@ export async function openapiToTypescriptClient({
                 commonHttpServiceImportPath: commonHttpService.importPath,
                 commonHttpServiceClassName: commonHttpService.className,
                 clientConfig: generateConfig.client,
-                generatedServiceImports: generatedServices ? generatedServices.services : [],
+                generatedServiceImports: generatedServices?.services ?? [],
                 servers: document.servers ?? [],
                 info: document.info,
                 paths: extractedTags.rest,
@@ -1136,7 +1142,8 @@ export async function openapiToTypescriptClient({
                 responseBinaryType: generateConfig.operations?.responseBinaryType ?? 'blob',
                 binaryTypes,
                 jsDocRenderConfig: generateConfig.jsDoc,
-                commentsConfig: generateConfig.comments
+                commentsConfig: generateConfig.comments,
+                deprecatedOperations: generatedServices?.deprecatedOperations ?? {}
             })
         );
     }

test/pet-store/api-typescript-generator-config.ts

@@ -18,7 +18,8 @@ export default async function (): Promise<ApiTypescriptGeneratorConfig> {
                 },
                 operations: {
                     validateResponse: true,
-                    makeResponseValidationSchemasExtensible: true
+                    makeResponseValidationSchemasExtensible: true,
+                    showDeprecatedWarnings: true
                 },
                 validation: {
                     library: 'zod'