fix: fix bug #525 (#533)

* fix: fix bug #525

* chore: clean code

Author: rookie-luochao

.changeset/nice-tips-listen.md

@@ -0,0 +1,5 @@
+---
+'openapi-ts-request': patch
+---
+
+fix: fix bug #525

README-en_US.md

@@ -252,6 +252,7 @@ openapi -i ./spec.json -o ./apis
 | isOnlyGenTypeScriptType | no | boolean | false | only generate typescript type |
 | isCamelCase | no | boolean | true | camelCase naming of controller files and request client |
 | isSupportParseEnumDesc | no | boolean | false | parse enum description to generate enum label, format example: `UserRole:User(Normal User)=0,Agent(Agent)=1,Admin(Administrator)=2` |
+| binaryMediaTypes | no | string[] | - | custom binary media types list, default includes: ['application/octet-stream', 'application/pdf', 'image/*', 'video/*', 'audio/*'] |
 | hook | no | [Custom Hook](#Custom-Hook) | - | custom hook |
 
 ## Custom Hook

README.md

@@ -1,5 +1,3 @@
-<!-- TODO:需要修改文档, 添加参数, 添加apifox的配置支持 -->
-
 ## 介绍
 
 [![GitHub Repo stars](https://img.shields.io/github/stars/openapi-ui/openapi-ts-request?style=social)](https://github.com/openapi-ui/openapi-ts-request) [![npm (scoped)](https://img.shields.io/npm/v/openapi-ts-request)](https://www.npmjs.com/package/openapi-ts-request) ![GitHub tag](https://img.shields.io/github/v/tag/openapi-ui/openapi-ts-request?include_prereleases)
@@ -50,8 +48,6 @@ pnpm i openapi-ts-request -D
 import type { GenerateServiceProps } from 'openapi-ts-request';
 
 export default {
-  // schemaPath: './openapi.json', // 本地openapi文件
-  // serversPath: './src/apis', // 接口存放路径
   schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
 } as GenerateServiceProps;
 ```
@@ -254,6 +250,7 @@ openapi --i ./spec.json --o ./apis
 | isOnlyGenTypeScriptType | 否 | boolean | false | 仅生成 typescript 类型 |
 | isCamelCase | 否 | boolean | true | 小驼峰命名文件和请求函数 |
 | isSupportParseEnumDesc | 否 | boolean | false | 解析枚举描述生成枚举标签，格式参考：`系统用户角色:User(普通用户)=0,Agent(经纪人)=1,Admin(管理员)=2` |
+| binaryMediaTypes | 否 | string[] | - | 自定义二进制媒体类型列表，默认包含：['application/octet-stream', 'application/pdf', 'image/*', 'video/*', 'audio/*'] |
 | hook | 否 | [Custom Hook](#Custom-Hook) | - | 自定义 hook |
 
 ## 自定义 Hook

src/generator/serviceGenarator.ts

@@ -2,7 +2,6 @@ import { existsSync, readFileSync } from 'fs';
 import { globSync } from 'glob';
 import type { Dictionary } from 'lodash';
 import {
-  // camelCase,
   entries,
   filter,
   find,
@@ -81,7 +80,10 @@ import { type MergeOption } from './type';
 import {
   capitalizeFirstLetter,
   genDefaultFunctionName,
+  getAxiosResponseType,
   getBasePrefix,
+  getBinaryMediaTypes,
+  getBinaryResponseType,
   getDefaultFileTag,
   getDefaultType,
   getFinalFileName,
@@ -92,13 +94,13 @@ import {
   isAllNumeric,
   isArraySchemaObject,
   isBinaryArraySchemaObject,
+  isBinaryMediaType,
   isNonArraySchemaObject,
   isReferenceObject,
   isSchemaObject,
   markAllowedSchema,
   parseDescriptionEnum,
   replaceDot,
-  // resolveFunctionName,
   resolveRefs,
   resolveTypeName,
 } from './util';
@@ -1152,6 +1154,7 @@ export default class ServiceGenerator {
       mediaType: '*/*',
       type: 'unknown',
       isAnonymous: false,
+      responseType: undefined as string | undefined,
     };
 
     if (!response) {
@@ -1160,9 +1163,16 @@ export default class ServiceGenerator {
 
     const resContent: ContentObject | undefined = response.content;
     const resContentMediaTypes = keys(resContent);
+
+    // 检测二进制流媒体类型
+    const binaryMediaTypes = getBinaryMediaTypes(this.config.binaryMediaTypes);
+    const binaryMediaType = resContentMediaTypes.find((mediaType) =>
+      isBinaryMediaType(mediaType, binaryMediaTypes)
+    );
+
     const mediaType = resContentMediaTypes.includes('application/json')
       ? 'application/json'
-      : resContentMediaTypes[0]; // 优先使用 application/json
+      : binaryMediaType || resContentMediaTypes[0]; // 优先使用 application/json，然后是二进制类型
 
     if (!isObject(resContent) || !mediaType) {
       return defaultResponse;
@@ -1174,8 +1184,20 @@ export default class ServiceGenerator {
       mediaType,
       type: 'unknown',
       isAnonymous: false,
+      responseType: undefined as string | undefined,
     };
 
+    // 如果是二进制媒体类型，直接返回二进制类型
+    if (isBinaryMediaType(mediaType, binaryMediaTypes)) {
+      const binaryType = getBinaryResponseType();
+      responseSchema.type = binaryType;
+
+      // 自动为二进制响应添加 responseType 配置
+      responseSchema.responseType = getAxiosResponseType(binaryType);
+
+      return responseSchema;
+    }
+
     if (isReferenceObject(schema)) {
       const refName = getLastRefName(schema.$ref);
       const childrenSchema = components.schemas[refName];
@@ -1306,14 +1328,26 @@ export default class ServiceGenerator {
 
     const resContent: ContentObject = response.content;
     const resContentMediaTypes = keys(resContent);
+
+    // 检测二进制流媒体类型
+    const binaryMediaTypes = getBinaryMediaTypes(this.config.binaryMediaTypes);
+    const binaryMediaType = resContentMediaTypes.find((mediaType) =>
+      isBinaryMediaType(mediaType, binaryMediaTypes)
+    );
+
     const mediaType = resContentMediaTypes.includes('application/json')
       ? 'application/json'
-      : resContentMediaTypes[0];
+      : binaryMediaType || resContentMediaTypes[0];
 
     if (!isObject(resContent) || !mediaType) {
       return 'unknown';
     }
 
+    // 如果是二进制媒体类型，直接返回二进制类型
+    if (isBinaryMediaType(mediaType, binaryMediaTypes)) {
+      return getBinaryResponseType();
+    }
+
     let schema = (resContent[mediaType].schema ||
       DEFAULT_SCHEMA) as SchemaObject;
 

src/generator/util.ts

@@ -572,3 +572,77 @@ export const parseDescriptionEnum = (
 
   return enumMap;
 };
+
+/**
+ * 获取默认的二进制媒体类型列表
+ */
+export const getDefaultBinaryMediaTypes = (): string[] => {
+  return [
+    'application/octet-stream',
+    'application/pdf',
+    'application/zip',
+    'application/x-zip-compressed',
+    'image/*',
+    'video/*',
+    'audio/*',
+  ];
+};
+
+/**
+ * 获取二进制媒体类型列表
+ * 支持配置自定义二进制媒体类型
+ * @param customBinaryTypes 自定义二进制媒体类型列表
+ */
+export const getBinaryMediaTypes = (
+  customBinaryTypes: string[] = []
+): string[] => {
+  const defaultBinaryTypes = getDefaultBinaryMediaTypes();
+  return [...defaultBinaryTypes, ...customBinaryTypes];
+};
+
+/**
+ * 检测是否为二进制媒体类型
+ * @param mediaType 媒体类型
+ * @param binaryMediaTypes 二进制媒体类型列表
+ */
+export const isBinaryMediaType = (
+  mediaType: string,
+  binaryMediaTypes: string[]
+): boolean => {
+  return binaryMediaTypes.some((type) => {
+    if (type.endsWith('/*')) {
+      // 处理通配符类型，如 image/*, video/*
+      const prefix = type.slice(0, -1);
+      return mediaType.startsWith(prefix);
+    }
+    return mediaType === type;
+  });
+};
+
+/**
+ * 获取二进制响应类型
+ * 默认返回 Blob，这是浏览器环境中最常用的二进制类型
+ */
+export const getBinaryResponseType = (): string => {
+  return 'Blob';
+};
+
+/**
+ * 获取 axios responseType 配置
+ * 根据二进制响应类型返回对应的 responseType
+ * @param binaryType 二进制类型
+ */
+export const getAxiosResponseType = (binaryType: string): string => {
+  switch (binaryType.toLowerCase()) {
+    case 'blob':
+      return 'blob';
+    case 'arraybuffer':
+      return 'arraybuffer';
+    case 'uint8array':
+      return 'arraybuffer'; // Uint8Array 需要从 ArrayBuffer 转换
+    case 'buffer':
+      return 'arraybuffer'; // Node.js Buffer 需要从 ArrayBuffer 转换
+    default:
+      return 'blob';
+  }
+};

src/index.ts

@@ -172,6 +172,11 @@ export type GenerateServiceProps = {
    * 多网关唯一标识
    */
   uniqueKey?: string;
+  /**
+   * 自定义二进制媒体类型列表
+   * 默认包含: ['application/octet-stream', 'application/pdf', 'image/*', 'video/*', 'audio/*']
+   */
+  binaryMediaTypes?: string[];
   /**
    * 自定义 hook
    */

templates/serviceController.njk

@@ -128,6 +128,9 @@
         return request{{ ("<" + api.response.type + ">") | safe if genType === "ts" }}('{{ api.path }}', {
       {% endif -%}
         method: '{{ api.method | upper }}',
+        {%- if api.response.responseType %}
+        responseType: '{{ api.response.responseType }}',
+        {%- endif %}
         {%- if api.hasHeader and api.body.mediaType %}
           headers: {
             {%- if api.body.mediaType %}

test/__snapshots__/common/测试文件下载 API.snap

@@ -0,0 +1,73 @@
+/* eslint-disable */
+// @ts-ignore
+import { queryOptions, useMutation } from '@tanstack/react-query';
+import type { DefaultError } from '@tanstack/react-query';
+import request from 'axios';
+
+import * as apis from './fileId';
+import * as API from './types';
+
+/** 下载文件 根据文件ID下载对应的文件流。 GET /files/${param0}/download */
+export function filesFileIdDownloadUsingGetQueryOptions(options: {
+  // 叠加生成的Param类型 (非body参数openapi默认没有生成对象)
+  params: API.FilesFileIdDownloadUsingGetParams;
+  options?: { [key: string]: unknown };
+}) {
+  return queryOptions({
+    queryFn: ({ queryKey }) => {
+      return apis.filesFileIdDownloadUsingGet(queryKey[1] as typeof options);
+    },
+    queryKey: ['filesFileIdDownloadUsingGet', options],
+  });
+}
+/* eslint-disable */
+// @ts-ignore
+import request from 'axios';
+
+import * as API from './types';
+
+/** 下载文件 根据文件ID下载对应的文件流。 GET /files/${param0}/download */
+export function filesFileIdDownloadUsingGet({
+  params,
+  options,
+}: {
+  // 叠加生成的Param类型 (非body参数openapi默认没有生成对象)
+  params: API.FilesFileIdDownloadUsingGetParams;
+  options?: { [key: string]: unknown };
+}) {
+  const { fileId: param0, ...queryParams } = params;
+
+  return request<Blob>(`/files/${param0}/download`, {
+    method: 'GET',
+    responseType: 'blob',
+    params: { ...queryParams },
+    ...(options || {}),
+  });
+}
+/* eslint-disable */
+// @ts-ignore
+export * from './types';
+
+export * from './fileId';
+export * from './fileId.reactquery';
+/* eslint-disable */
+// @ts-ignore
+
+export type FilesFileIdDownloadUsingGetParams = {
+  /** 文件的唯一标识符 */
+  fileId: string;
+};
+
+export type FilesFileIdDownloadUsingGetResponses = {
+  /**
+   * 文件下载成功
+   */
+  200: Blob;
+  /**
+   * 文件未找到
+   */
+  404: {
+    code?: number;
+    message?: string;
+  };
+};

test/common.spec.ts

@@ -497,4 +497,18 @@ export async function ${api.functionName}(${api.body ? `data: ${api.body.type}`
       readGeneratedFiles('./apis/components-parameters')
     ).resolves.toMatchFileSnapshot(getSnapshotDir(ctx));
   });
+
+  it('测试文件下载 API', async (ctx) => {
+    await openAPI.generateService({
+      schemaPath: join(
+        import.meta.dirname,
+        './example-files/openapi-file-download.json'
+      ),
+      serversPath: './apis/file-download',
+      isGenReactQuery: true,
+    });
+    await expect(
+      readGeneratedFiles('./apis/file-download')
+    ).resolves.toMatchFileSnapshot(getSnapshotDir(ctx));
+  });
 });