Merge pull request #278 from openapi-ui/main

feat: support custom templates

Author: rookie-luochao

.changeset/icy-candles-wear.md

@@ -0,0 +1,5 @@
+---
+'openapi-ts-request': patch
+---
+
+feat: support custom templates

README-en_US.md

@@ -262,17 +262,22 @@ openapi -i ./spec.json -o ./apis
 | customClassName | (tagName: string) => string | custom tag name |
 | customType | ({<br>schemaObject: SchemaObject \| ReferenceObject,<br>namespace: string,<br>originGetType:(schemaObject: SchemaObject \| ReferenceObject, namespace: string, schemas?: ComponentsObject['schemas']) => string,<br>schemas?: ComponentsObject['schemas'],<br>}) => string | custom type <br> _returning a non-string will use the default method to get the type_ |
 | customFileNames | (<br>operationObject: OperationObject,<br>apiPath: string,<br>apiMethod: string,<br>) => string[] | custom generate request client controller file name, can return multiple: generate multiple files. <br> _if the return value is empty, the default getFileNames is used_ |
+| customTemplates | {<br>[TypescriptFileType.serviceController]?: <T, U>(item: T, context: U) => string;<br>} | custom template, details see source code |
 
 ## Apifox-Config
 
 | attribute | type | description | required |
 | --- | --- | --- | --- |
 | projectId | string | project id | true |
+| apifoxToken | string | [get](https://docs.apifox.com/doc-5723694) | true |
 | local | string | language(default:zh-CN) | false |
 | apifoxVersion | string | default: 2024-03-28, [current apifox version](https://api.apifox.com/v1/versions) | false |
 | includeTags | \* or string[] | default: \* | false |
 | excludeTags | string[] | default: [] | false |
-| apifoxToken | string | [get](https://docs.apifox.com/doc-5723694) | true |
+| oasVersion | string | specify the version of the OpenAPI specification used for export, can have values such as "2.0", "3.0" or "3.1" | '3.0' |
+| exportFormat | string | specify the format of the exported OpenAPI file, can have values such as 'JSON' or 'YAML' | 'JSON' |
+| includeApifoxExtensionProperties | boolean | specify whether to include the OpenAPI specification extension fields `x-apifox` | false |
+| addFoldersToTags | boolean | specify whether to include the directory name of the interface in the tag field | false |
 
 ## JSON Schemas
 

README.md

@@ -264,17 +264,22 @@ openapi --i ./spec.json --o ./apis
 | customClassName | (tagName: string) => string | 自定义标签名 |
 | customType | ({<br>schemaObject: SchemaObject \| ReferenceObject,<br>namespace: string,<br>originGetType:(schemaObject: SchemaObject \| ReferenceObject, namespace: string, schemas?: ComponentsObject['schemas']) => string,<br>schemas?: ComponentsObject['schemas'],<br>}) => string | 自定义类型 <br> _返回非字符串将使用默认方法获取type_ |
 | customFileNames | (<br>operationObject: OperationObject,<br>apiPath: string,<br>apiMethod: string,<br>) => string[] | 自定义生成的请求客户端文件名称，可以返回多个文件名称的数组(表示生成多个文件). <br> _返回为空，则使用默认的方法获取_ |
+| customTemplates | {<br>[TypescriptFileType.serviceController]?: <T, U>(item: T, context: U) => string;<br>} | 自定义模板，详情请看源码 |
 
 ## Apifox-Config
 
 | 属性 | 类型 | 说明 | 必填 |
 | --- | --- | --- | --- |
 | projectId | string | 项目id | true |
-| local | string | 语言(默认:zh-CN) | false |
+| apifoxToken | string | [获取](https://docs.apifox.com/doc-5723694) | true |
+| local | string | 语言(默认: zh-CN) | false |
 | apifoxVersion | string | 默认: 2024-03-28, [获取当前版本](https://api.apifox.com/v1/versions) | false |
 | includeTags | \* 或 string[] | 默认: \* | false |
 | excludeTags | string[] | 默认: [] | false |
-| apifoxToken | string | [获取](https://docs.apifox.com/doc-5723694) | true |
+| oasVersion | string | 指定用于导出的 OpenAPI 规范的版本，可以有值如 "2.0"、"3.0"、"3.1" | '3.0' |
+| exportFormat | string | 指定导出的 OpenAPI 文件的格式，可以有值如 'JSON' 或 'YAML' | 'JSON' |
+| includeApifoxExtensionProperties | boolean | 指定是否包含 Apifox 的 OpenAPI 规范扩展字段 `x-apifox` | false |
+| addFoldersToTags | boolean | 指定是否在标签字段中包含接口的目录名称 | false |
 
 ## JSON Schemas
 

src/generator/serviceGenarator.ts

@@ -70,6 +70,7 @@ import {
   ICustomSchemaObject,
   IPropObject,
   ISchemaItem,
+  IServiceControllerPayload,
   ITypeItem,
   ITypescriptFileType,
   type MergeOption,
@@ -329,18 +330,39 @@ export default class ServiceGenerator {
 
       // 生成 service controller 文件
       this.getServiceTPConfigs().forEach((tp) => {
+        const { list, ...restTp } = tp;
+        const payload: Omit<typeof tp, 'list'> &
+          IServiceControllerPayload<typeof list> = {
+          namespace: this.config.namespace,
+          requestOptionsType: this.config.requestOptionsType,
+          requestImportStatement: this.config.requestImportStatement,
+          interfaceFileName: interfaceFileName,
+          list,
+          ...restTp,
+        };
+        const hookCustomTemplateService =
+          this.config.hook?.customTemplates?.[
+            TypescriptFileType.serviceController
+          ];
+
+        if (hookCustomTemplateService) {
+          payload.list = list.map((item) => {
+            return {
+              customTemplate: true,
+              data: hookCustomTemplateService<typeof item, typeof payload>(
+                item,
+                payload
+              ),
+            };
+          });
+        }
+
         const hasError = this.genFileFromTemplate(
           isGenJavaScript
             ? getFinalFileName(`${tp.className}.js`)
             : getFinalFileName(`${tp.className}.ts`),
           TypescriptFileType.serviceController,
-          {
-            namespace: this.config.namespace,
-            requestOptionsType: this.config.requestOptionsType,
-            requestImportStatement: this.config.requestImportStatement,
-            interfaceFileName: interfaceFileName,
-            ...tp,
-          }
+          payload
         );
 
         prettierError.push(hasError);

src/generator/type.ts

@@ -69,3 +69,16 @@ type MergerOptionProps = {
 };
 
 export type MergerOptions = MergeOption & Partial<MergerOptionProps>;
+
+export type IServiceControllerPayload<T> = {
+  namespace: string;
+  requestOptionsType: string;
+  requestImportStatement: string;
+  interfaceFileName: string;
+  list:
+    | {
+        customTemplate: boolean;
+        data: string;
+      }[]
+    | T;
+};

src/index.ts

@@ -1,6 +1,7 @@
 import { isEmpty, map } from 'lodash';
 
 import { PriorityRule, ReactQueryMode } from './config';
+import { TypescriptFileType } from './generator/config';
 import { mockGenerator } from './generator/mockGenarator';
 import ServiceGenerator from './generator/serviceGenarator';
 import { APIDataType } from './generator/type';
@@ -233,6 +234,18 @@ export type GenerateServiceProps = {
       apiPath: string,
       apiMethod: string
     ) => string[] | null;
+    /**
+     * 自定义模板
+     */
+    customTemplates?: {
+      /**
+       * 自定义 serviceController 模板
+       */
+      [TypescriptFileType.serviceController]?: <T, U>(
+        item: T,
+        context: U
+      ) => string;
+    };
   };
 };
 

src/readConfig.ts

@@ -26,7 +26,6 @@ export const readConfig = async <T = unknown>({
     } else {
       return (await explorerSync.search()?.config) as T;
     }
-    // eslint-disable-next-line no-unused-vars
   } catch (error) {
     return undefined;
   }