fix(typescript-axios-slim): add observe response mode

Author: scarf005

docs/generators/typescript-axios-slim.md

@@ -49,6 +49,8 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |withSeparateModelsAndApi|Put the model and api in separate folders and in separate classes. This requires in addition a value for 'apiPackage' and 'modelPackage'| |false|
 |withoutPrefixEnums|Don't prefix enum names with class names| |false|
 
+Generated API methods default to resolving payload data. Pass `observe: 'response'` in the request config to receive `AxiosResponse<T>` when you need headers or status metadata.
+
 ## IMPORT MAPPING
 
 | Type/Alias | Imports |

modules/openapi-generator/src/main/resources/typescript-axios-slim/README.mustache

@@ -2,7 +2,7 @@
 
 This generator creates TypeScript/JavaScript client that utilizes [axios](https://github.com/axios/axios). The generated Node module can be used in the following environments:
 
-> `typescript-axios-slim` intentionally differs from `typescript-axios`: it removes `AxiosParamCreator`, `Fp`, and `Factory` layers, always uses a single request-parameter object per operation, and emits direct class methods with request-parameter schema validation.
+> `typescript-axios-slim` intentionally differs from `typescript-axios`: it removes `AxiosParamCreator`, `Fp`, and `Factory` layers, always uses a single request-parameter object per operation, and emits direct class methods with request-parameter schema validation. By default methods resolve payload data directly; pass `observe: 'response'` to receive full `AxiosResponse` values when you need headers or status metadata.
 
 Environment
 * Node.js

modules/openapi-generator/src/main/resources/typescript-axios-slim/api.mustache

@@ -5,7 +5,7 @@
 
 {{^withSeparateModelsAndApi}}
 import type { Configuration } from './configuration{{importFileExtension}}';
-import type { AxiosInstance, RawAxiosRequestConfig } from 'axios';
+import type { AxiosInstance, RawAxiosRequestConfig, AxiosResponse } from 'axios';
 import globalAxios from 'axios';
 {{#withNodeImports}}
 // URLSearchParams not necessarily used
@@ -19,6 +19,7 @@ import * as v from 'valibot';
 // Some imports not used depending on template conditions
 // @ts-ignore
 import { DUMMY_BASE_URL, validateRequestParameters, withParams, setApiKeyToObject, setBasicAuthToObject, setBearerAuthToObject, setOAuthToObject, setSearchParams, serializeDataIfNeeded, toPathString, replaceWithSerializableTypeIfNeeded{{#withAWSV4Signature}}, setAWS4SignatureInterceptor{{/withAWSV4Signature}} } from './common{{importFileExtension}}';
+import type { ObserveOptions, ResponseObserveOptions } from './common{{importFileExtension}}';
 import type { RequestArgs } from './base{{importFileExtension}}';
 // @ts-ignore
 import { BASE_PATH, COLLECTION_FORMATS, BaseAPI, RequiredError, operationServerMap } from './base{{importFileExtension}}';

modules/openapi-generator/src/main/resources/typescript-axios-slim/apiInner.mustache

@@ -5,7 +5,7 @@
 
 
 import type { Configuration } from '{{apiRelativeToRoot}}configuration{{importFileExtension}}';
-import type { AxiosInstance, RawAxiosRequestConfig } from 'axios';
+import type { AxiosInstance, RawAxiosRequestConfig, AxiosResponse } from 'axios';
 import globalAxios from 'axios';
 {{#withNodeImports}}
 // URLSearchParams not necessarily used
@@ -19,6 +19,7 @@ import * as v from 'valibot';
 // Some imports not used depending on template conditions
 // @ts-ignore
 import { DUMMY_BASE_URL, validateRequestParameters, withParams, setApiKeyToObject, setBasicAuthToObject, setBearerAuthToObject, setOAuthToObject, setSearchParams, serializeDataIfNeeded, toPathString, replaceWithSerializableTypeIfNeeded{{#withAWSV4Signature}}, setAWS4SignatureInterceptor{{/withAWSV4Signature}} } from '{{apiRelativeToRoot}}common{{importFileExtension}}';
+import type { ObserveOptions, ResponseObserveOptions } from '{{apiRelativeToRoot}}common{{importFileExtension}}';
 // @ts-ignore
 import { BASE_PATH, COLLECTION_FORMATS, BaseAPI, RequiredError, operationServerMap } from '{{apiRelativeToRoot}}base{{importFileExtension}}';
 {{#imports}}
@@ -59,7 +60,8 @@ export interface {{classname}}Interface {
      * @deprecated{{/isDeprecated}}
      * @throws {RequiredError}
      */
-    {{nickname}}({{#allParams.0}}requestParameters{{^hasRequiredParams}}?{{/hasRequiredParams}}: {{classname}}{{operationIdCamelCase}}Request, {{/allParams.0}}options?: RawAxiosRequestConfig): Promise<{{{returnType}}}{{^returnType}}void{{/returnType}}>;
+    {{nickname}}({{#allParams.0}}requestParameters{{^hasRequiredParams}}?{{/hasRequiredParams}}: {{classname}}{{operationIdCamelCase}}Request, {{/allParams.0}}options: ResponseObserveOptions): Promise<AxiosResponse<{{{returnType}}}{{^returnType}}void{{/returnType}}>>;
+    {{nickname}}({{#allParams.0}}requestParameters{{^hasRequiredParams}}?{{/hasRequiredParams}}: {{classname}}{{operationIdCamelCase}}Request, {{/allParams.0}}options?: ObserveOptions): Promise<{{{returnType}}}{{^returnType}}void{{/returnType}}>;
 
 {{/operation}}
 }
@@ -105,14 +107,17 @@ export class {{classname}} extends BaseAPI {
      * @deprecated{{/isDeprecated}}
      * @throws {RequiredError}
      */
-    public async {{nickname}}({{#allParams.0}}requestParameters: {{classname}}{{operationIdCamelCase}}Request{{^hasRequiredParams}} = {}{{/hasRequiredParams}}, {{/allParams.0}}options: RawAxiosRequestConfig = {}): Promise<{{{returnType}}}{{^returnType}}void{{/returnType}}> {
+    public async {{nickname}}({{#allParams.0}}requestParameters: {{classname}}{{operationIdCamelCase}}Request{{^hasRequiredParams}} = {}{{/hasRequiredParams}}, {{/allParams.0}}options: ResponseObserveOptions): Promise<AxiosResponse<{{{returnType}}}{{^returnType}}void{{/returnType}}>>;
+    public async {{nickname}}<TObserve extends ObserveOptions = ObserveOptions>({{#allParams.0}}requestParameters: {{classname}}{{operationIdCamelCase}}Request{{^hasRequiredParams}} = {}{{/hasRequiredParams}}, {{/allParams.0}}options: TObserve = {} as TObserve): Promise<TObserve extends ResponseObserveOptions ? AxiosResponse<{{{returnType}}}{{^returnType}}void{{/returnType}}> : {{{returnType}}}{{^returnType}}void{{/returnType}}> {
     {{#allParams.0}}
         validateRequestParameters('{{nickname}}', {{nickname}}RequestSchema, requestParameters);
     {{/allParams.0}}
         const localVarPath = {{#pathParams}}withParams(`{{{path}}}`, { {{#pathParams}}"{{baseName}}": requestParameters.{{paramName}}, {{/pathParams}} }){{/pathParams}}{{^pathParams}}`{{{path}}}`{{/pathParams}};
         const localVarUrlObj = new URL(localVarPath, DUMMY_BASE_URL);
         const baseOptions = this.configuration ? this.configuration.baseOptions : undefined;
-        const localVarRequestOptions = { method: '{{httpMethod}}', ...baseOptions, ...options } as RawAxiosRequestConfig;
+        const localVarObserve = options.observe ?? 'body';
+        const { observe, ...axiosOptions } = options;
+        const localVarRequestOptions = { method: '{{httpMethod}}', ...baseOptions, ...axiosOptions } as RawAxiosRequestConfig;
         const localVarHeaderParameter = {} as any;
         const localVarQueryParameter = {} as any;{{#vendorExtensions}}{{#hasFormParams}}
         const localVarFormParams = new {{^multipartFormData}}URLSearchParams(){{/multipartFormData}}{{#multipartFormData}}((this.configuration && this.configuration.formDataCtor) || FormData)(){{/multipartFormData}};{{/hasFormParams}}{{/vendorExtensions}}
@@ -299,8 +304,12 @@ export class {{classname}} extends BaseAPI {
         const effectiveBasePath = localVarOperationServerBasePath || this.basePath || BASE_PATH;
         localVarRequestOptions.url = (this.axios.defaults.baseURL ? '' : this.configuration?.basePath ?? effectiveBasePath) + toPathString(localVarUrlObj);
 
-        const localVarResponse = await this.axios.request<{{{returnType}}}{{^returnType}}void{{/returnType}}>(localVarRequestOptions);
-        return localVarResponse.data;
+        const localVarResponse = await this.axios.request<{{{returnType}}}{{^returnType}}void{{/returnType}}, AxiosResponse<{{{returnType}}}{{^returnType}}void{{/returnType}}>>(localVarRequestOptions);
+        if (localVarObserve === 'response') {
+            return localVarResponse as TObserve extends ResponseObserveOptions ? AxiosResponse<{{{returnType}}}{{^returnType}}void{{/returnType}}> : {{{returnType}}}{{^returnType}}void{{/returnType}};
+        }
+
+        return localVarResponse.data as TObserve extends ResponseObserveOptions ? AxiosResponse<{{{returnType}}}{{^returnType}}void{{/returnType}}> : {{{returnType}}}{{^returnType}}void{{/returnType}};
     }
     {{^-last}}
 

modules/openapi-generator/src/main/resources/typescript-axios-slim/common.mustache

@@ -4,7 +4,7 @@
 
 import type { Configuration } from "./configuration{{importFileExtension}}";
 import type { RequestArgs } from "./base{{importFileExtension}}";
-import type { AxiosInstance, AxiosResponse } from 'axios';
+import type { AxiosInstance, AxiosResponse, RawAxiosRequestConfig } from 'axios';
 import * as v from 'valibot';
 {{#withAWSV4Signature}}
 import { aws4Interceptor } from "aws4-axios";
@@ -16,6 +16,11 @@ import { URL, URLSearchParams } from 'url';
 
 export const DUMMY_BASE_URL = 'https://example.com'
 
+export type Observe = 'body' | 'response';
+export type BodyObserveOptions = RawAxiosRequestConfig & { observe?: 'body' };
+export type ResponseObserveOptions = RawAxiosRequestConfig & { observe: 'response' };
+export type ObserveOptions = BodyObserveOptions | ResponseObserveOptions;
+
 /**
  *
  * @throws {RequiredError}

modules/openapi-generator/src/test/java/org/openapitools/codegen/typescript/axios/TypeScriptAxiosSlimParityTest.java

@@ -125,10 +125,24 @@ public void shouldReturnPayloadDataFromObjectOrientedMethods() throws Exception
         IdentitySurface slimSurface = generateIdentity("typescript-axios-slim", EDGE_CASE_SPEC, NO_CUSTOMIZER);
         String apiSource = String.join(" ", slimSurface.apiFiles.values());
 
-        assertTrue(apiSource.contains("): Promise<"), "Slim API methods should return Promise payload types");
+        assertTrue(apiSource.contains("<TObserve extends ObserveOptions = ObserveOptions>"), "Slim API methods should expose observe-aware generics");
+        assertTrue(apiSource.contains("options: TObserve = {} as TObserve): Promise<TObserve extends ResponseObserveOptions ? AxiosResponse<"), "Slim API methods should return payload types by default through observe-aware generics");
         assertFalse(apiSource.contains("AxiosPromise<"), "Slim API interface should not expose AxiosPromise return wrappers");
-        assertFalse(apiSource.contains("Promise<AxiosResponse<"), "Slim API class should not return Promise<AxiosResponse<T>>");
-        assertTrue(apiSource.contains("return localVarResponse.data;"), "Slim API class should resolve axios response data directly");
+        assertTrue(apiSource.contains("options: ResponseObserveOptions): Promise<AxiosResponse<"), "Slim API methods should preserve explicit response overloads when observe=response");
+        assertTrue(apiSource.contains("const localVarObserve = options.observe ?? 'body';"), "Slim API class should default observe mode to body");
+        assertTrue(apiSource.contains("return localVarResponse as TObserve extends ResponseObserveOptions ? AxiosResponse<"), "Slim API class should return raw axios responses when observe=response");
+        assertTrue(apiSource.contains("return localVarResponse.data as TObserve extends ResponseObserveOptions ? AxiosResponse<"), "Slim API class should resolve axios response data directly");
+    }
+
+    @Test(description = "slim: observe options are exported for typed response access")
+    public void shouldExportObserveOptionsForTypedResponseAccess() throws Exception {
+        IdentitySurface slimSurface = generateIdentity("typescript-axios-slim", EDGE_CASE_SPEC, NO_CUSTOMIZER);
+        String commonSource = slimSurface.supportingFiles.getOrDefault("common.ts", "");
+        String apiSource = String.join(" ", slimSurface.apiFiles.values());
+
+        assertTrue(commonSource.contains("export type Observe = 'body' | 'response';"), "Slim common runtime should export observe mode types");
+        assertTrue(commonSource.contains("export type ObserveOptions = BodyObserveOptions | ResponseObserveOptions;"), "Slim common runtime should export observe option union types");
+        assertTrue(apiSource.contains("const { observe, ...axiosOptions } = options;"), "Slim API class should strip observe before forwarding axios options");
     }
 
     @Test(description = "slim: useSingleRequestParameter remains enabled even if configured false")
@@ -181,6 +195,12 @@ private IdentitySurface extractIdentity(Path outputDir) throws IOException {
             surface.modelFiles.put(relativePath, normalize(Files.readString(modelFile)));
         }
 
+        List<Path> supportingFiles = collectSupportingFiles(outputDir);
+        for (Path supportingFile : supportingFiles) {
+            String relativePath = normalizePath(outputDir.relativize(supportingFile));
+            surface.supportingFiles.put(relativePath, normalize(Files.readString(supportingFile)));
+        }
+
         assertTrue(!surface.requestInterfaces.isEmpty() || !surface.apiInterfaceMethods.isEmpty(),
                 "No comparable request/response surface was extracted from generated sources under " + outputDir);
 
@@ -226,6 +246,18 @@ private List<Path> collectModelFiles(Path outputDir) throws IOException {
         return sorted;
     }
 
+    private List<Path> collectSupportingFiles(Path outputDir) throws IOException {
+        LinkedHashSet<Path> files = new LinkedHashSet<>();
+        Path common = outputDir.resolve("common.ts");
+        if (Files.exists(common)) {
+            files.add(common);
+        }
+
+        List<Path> sorted = new ArrayList<>(files);
+        Collections.sort(sorted);
+        return sorted;
+    }
+
     private void extractRequestInterfaces(Map<String, String> target, String apiSource) {
         Matcher matcher = REQUEST_INTERFACE_PATTERN.matcher(apiSource);
         while (matcher.find()) {
@@ -241,14 +273,24 @@ private void extractApiInterfaceMethods(Map<String, Set<String>> target, String
             Matcher methodMatcher = API_INTERFACE_METHOD_PATTERN.matcher(interfaceBody);
             while (methodMatcher.find()) {
                 String methodName = methodMatcher.group(1);
-                String params = normalize(methodMatcher.group(2));
+                String rawParams = methodMatcher.group(2);
+                if (rawParams.contains("ResponseObserveOptions")) {
+                    continue;
+                }
+                String params = normalizeComparableParams(rawParams);
                 String returnType = normalizeComparableReturnType(methodMatcher.group(3));
                 target.computeIfAbsent(interfaceName, ignored -> new TreeSet<>())
                         .add(methodName + "(" + params + "):" + returnType);
             }
         }
     }
 
+    private String normalizeComparableParams(String params) {
+        return normalize(params)
+                .replace("<TObserve extends ObserveOptions = ObserveOptions>", "")
+                .replace("ObserveOptions", "RawAxiosRequestConfig");
+    }
+
     private String normalizeComparableReturnType(String returnType) {
         String current = normalize(returnType);
         while (true) {
@@ -327,6 +369,7 @@ private static final class IdentitySurface {
         private final Map<String, String> operationEnums = new TreeMap<>();
         private final Map<String, String> modelFiles = new TreeMap<>();
         private final Map<String, String> apiFiles = new TreeMap<>();
+        private final Map<String, String> supportingFiles = new TreeMap<>();
 
         private Set<String> allMethodNames() {
             Set<String> names = new TreeSet<>();