Merge pull request #248 from FrontEndDev-org/feat/custom-method-name

feat(parser): 新增nameFormatter支持自定义方法名 Implement #247

Author: cloudcome

README.md

@@ -154,15 +154,29 @@ console.log(pet);
 | `openAPIs`    | `OpenAPIOptions[]` | `true`  | OpenAPIOptions 列表，至少需要配置一个 | 无                           |
 
 ## `ParserOptions` 签名：
-| 参数名                    | 类型       | 可选性     | 描述         | 默认值                |
-|------------------------|----------|---------|------------|--------------------|
-| `cwd`                  | `string` | `false` | 当前工作路径     | `process.cwd()`    |
-| `okCode`               | `number` | `false` | ok 的响应码    | `200`              |
-| `okMediaType`          | `number` | `false` | ok 的响应类型   | `application/json` |
-| `requestPathTypeName`  | `string` | `false` | 请求路径参数类型名称 | `ReqPath`          |
-| `requestQueryTypeName` | `string` | `false` | 请求查询参数类型名称 | `ReqParams`        |
-| `requestBodyTypeName`  | `string` | `false` | 请求体参数类型名称  | `ReqData`          |
-| `responseBodyTypeName` | `string` | `false` | 响应体参数类型名称  | `ResData`          |
+| 参数名                    | 类型         | 可选性     | 描述                                                             | 默认值                    |
+|------------------------|------------|---------|----------------------------------------------------------------|------------------------|
+| `cwd`                  | `string`   | `false` | 当前工作路径                                                         | `process.cwd()`        |
+| `okCode`               | `number`   | `false` | ok 的响应码                                                        | `200`                  |
+| `okMediaType`          | `number`   | `false` | ok 的响应类型                                                       | `application/json`     |
+| `nameFormatter`        | `function` | `false` | 自定义name格式化方法，函数签名 ```(props: NameFormatterProps) => string;``` | ```({name}) => name``` |
+| `requestPathTypeName`  | `string`   | `false` | 请求路径参数类型名称                                                     | `ReqPath`              |
+| `requestQueryTypeName` | `string`   | `false` | 请求查询参数类型名称                                                     | `ReqParams`            |
+| `requestBodyTypeName`  | `string`   | `false` | 请求体参数类型名称                                                      | `ReqData`              |
+| `responseBodyTypeName` | `string`   | `false` | 响应体参数类型名称                                                      | `ResData`              |
+
+<details>
+<summary>【点击展开】查看 NameFormatterProps 签名</summary>
+
+## `NameFormatterProps` 签名：
+| 参数名                   | 类型       | 可选性     | 描述                 | 默认值                         |
+|-----------------------|----------|---------|--------------------|-----------------------------|
+| `name`                | `string` | `true`  | 原始名称（经过内部处理，能保证唯一） | 无                           |
+| `method`              | `string` | `true`  | 方法                 | 无                           |
+| `path`                | `string` | `true`  | 路径                 | 无                           |
+| `operationId`         | `string` | `false` | operationId        | 无                           |
+
+</details>
 
 ## `PrinterOptions` 签名：
 | 参数名                   | 类型       | 可选性     | 描述                                  | 默认值                         |

src/parsers/BaseParser.ts

@@ -11,6 +11,7 @@ export class BaseParser {
     cwd: process.cwd(),
     okCode: 200,
     okMediaType: JSON_MIME,
+    nameFormatter: ({ name }) => name,
     requestPathTypeName: 'ReqPath',
     requestQueryTypeName: 'ReqParams',
     requestBodyTypeName: 'ReqData',

src/parsers/PathsParser.ts

@@ -42,7 +42,13 @@ export class PathsParser extends ComponentsParser {
   parseOperation(operation: OpenAPIV3.OperationObject): TypeOperation {
     const { parameters, requestBody: requestBodySchema } = operation;
     const { pathTypes, queryTypes } = this.parseOperationParameters(parameters);
-    const name = this.named.nextOperationId(this.parsingMethod, this.parsingUrl, operation.operationId);
+    const initialName = this.named.nextOperationId(this.parsingMethod, this.parsingUrl, operation.operationId);
+    const name = this.options.nameFormatter({
+      name: initialName,
+      method: this.parsingMethod,
+      url: this.parsingUrl,
+      operationId: operation.operationId,
+    });
     const requestPathTypeName = this.named.nextTypeName(name + this.options.requestPathTypeName);
     const requestQueryTypeName = this.named.nextTypeName(name + this.options.requestQueryTypeName);
     const requestBodyTypeName = this.named.nextTypeName(name + this.options.requestBodyTypeName);

src/parsers/types.ts

@@ -34,6 +34,13 @@ export interface TypeAlias extends TypeComments {
 export type TypeItem = TypeOrigin | TypeAlias;
 export type TypeList = TypeItem[];
 
+export interface NameFormatterProps {
+  name: string;
+  method: string;
+  url: string;
+  operationId?: string;
+}
+
 export interface ParserOptions {
   cwd?: string;
 
@@ -49,6 +56,7 @@ export interface ParserOptions {
    */
   okMediaType?: string;
 
+  nameFormatter?: (props: NameFormatterProps) => string;
   requestPathTypeName?: string;
   requestQueryTypeName?: string;
   requestBodyTypeName?: string;

test/parsers/PathsParser.test.ts

@@ -90,6 +90,54 @@ test('empty path item method responses keys + specify operationId', async () =>
   ]);
 });
 
+test('custom name formatter', async () => {
+  const parser = new PathsParser(
+    {
+      info: {
+        title: 'test',
+        version: '1.0.0',
+      },
+      openapi: '3.0.0',
+      paths: {
+        '/pet': {
+          get: {
+            operationId: 'findPet',
+            responses: {},
+          },
+        },
+        '/cat': {
+          get: {
+            responses: {},
+          },
+        },
+      },
+    },
+    {
+      nameFormatter: ({ name /*, method, url, operationId*/ }) => {
+        return `custom_${name}`;
+      },
+    }
+  );
+
+  const t = parser.parsePaths();
+  expect(t).toEqual<TypeOperations>([
+    {
+      name: `custom_getCat`,
+      method: OpenAPIV3.HttpMethods.GET,
+      url: '/cat',
+      request: {},
+      response: {},
+    },
+    {
+      name: `custom_findPet`,
+      method: OpenAPIV3.HttpMethods.GET,
+      url: '/pet',
+      request: {},
+      response: {},
+    },
+  ]);
+});
+
 test('operationId is reserved', async () => {
   const parser = new PathsParser({
     info: {