perf: 增加枚举类型注释 (#604)

* feat: 增加枚举类型注释

* feat: 完善枚举类型注释

* Enhance enum comments for performance tracking

---------

Co-authored-by: 故城 <1055120207@qq.com>

Author: vsqq0

.changeset/odd-webs-cover.md

@@ -0,0 +1,5 @@
+---
+'openapi-ts-request': patch
+---
+
+perf: 增加枚举注释

src/generator/serviceGenarator.ts

@@ -1507,6 +1507,7 @@ export default class ServiceGenerator {
       schemaObject,
       getType: (schema: ISchemaObject, namespace?: string) =>
         this.getType(schema, namespace),
+      openAPIData: this.openAPIData,
     });
   }
 

src/generator/serviceGeneratorHelper.ts

@@ -215,8 +215,9 @@ export function resolveAllOfObject(params: {
 export function getProps(params: {
   schemaObject: SchemaObject;
   getType: (schema: SchemaObject) => string;
+  openAPIData?: OpenAPIObject;
 }): IPropObject[] {
-  const { schemaObject, getType } = params;
+  const { schemaObject, getType, openAPIData } = params;
   const requiredPropKeys = schemaObject?.required ?? false;
   const properties = schemaObject.properties;
 
@@ -226,15 +227,35 @@ export function getProps(params: {
     // eslint-disable-next-line no-useless-escape
     propKey = propKey.replace(/[\[|\]]/g, '');
 
+    // 获取描述信息，如果是 $ref 引用，尝试获取引用对象的描述
+    let desc = [schema.title, schema.description]
+      .filter((item) => item)
+      .join(' ')
+      .replace(lineBreakReg, '');
+
+    // 如果是 $ref 引用，尝试获取引用对象的描述
+    if (isReferenceObject(schema) && openAPIData) {
+      const refName = getLastRefName(schema.$ref);
+      const refSchema = openAPIData.components?.schemas?.[
+        refName
+      ] as SchemaObject;
+      if (refSchema) {
+        const refDesc = [refSchema.title, refSchema.description]
+          .filter((item) => item)
+          .join(' ')
+          .replace(lineBreakReg, '');
+        if (refDesc) {
+          desc = desc + refDesc;
+        }
+      }
+    }
+
     // 复用 schema 部分字段
     return {
       ...schema,
       name: propKey,
       type: getType(schema),
-      desc: [schema.title, schema.description]
-        .filter((item) => item)
-        .join(' ')
-        .replace(lineBreakReg, ''),
+      desc: desc,
       // 如果没有 required 信息，默认全部是非必填
       required: requiredPropKeys
         ? requiredPropKeys.some((key) => key === propKey)

templates/enum.njk

@@ -4,6 +4,9 @@
 {%- if list.length > 0 %}
   {% for type in list -%}
     {%- if type.isEnum  %}
+      {%- if type.description%} 
+      /** {{ type.description }} */
+      {%- endif %}
       export enum {{ type.typeName | safe }} {{ type.type }};
 
       export type I{{ type.typeName | safe }} = keyof typeof {{ type.typeName }}

templates/interface.njk

@@ -43,6 +43,9 @@
       {%- endfor %}
     {%- else %}
       {%- if type.isEnum  %}
+        {%- if type.description%} 
+        /** {{ type.description }} */
+        {%- endif %}
         export enum {{ type.typeName | safe }} {{ type.type }};
 
         export type I{{ type.typeName | safe }} = keyof typeof {{ type.typeName }}

test/__snapshots__/common/小驼峰命名文件和请求函数.snap

@@ -411,6 +411,7 @@ export type PetUsingPutResponses = {
   405: unknown;
 };
 
+/** Order Status */
 export enum StatusEnum {
   'placed' = 'placed',
   'approved' = 'approved',
@@ -419,6 +420,7 @@ export enum StatusEnum {
 
 export type IStatusEnum = keyof typeof StatusEnum;
 
+/** pet status in the store */
 export enum StatusEnum2 {
   'available' = 'available',
   'pending' = 'pending',

test/__snapshots__/common/支持 null 类型作为默认值.snap

@@ -411,6 +411,7 @@ export type PetUsingPutResponses = {
   405: unknown;
 };
 
+/** Order Status */
 export enum StatusEnum {
   'placed' = 'placed',
   'approved' = 'approved',
@@ -419,6 +420,7 @@ export enum StatusEnum {
 
 export type IStatusEnum = keyof typeof StatusEnum;
 
+/** pet status in the store */
 export enum StatusEnum2 {
   'available' = 'available',
   'pending' = 'pending',

test/__snapshots__/common/正常命名文件和请求函数.snap

@@ -411,6 +411,7 @@ export type PetUsingPutResponses = {
   405: unknown;
 };
 
+/** Order Status */
 export enum StatusEnum {
   'placed' = 'placed',
   'approved' = 'approved',
@@ -419,6 +420,7 @@ export enum StatusEnum {
 
 export type IStatusEnum = keyof typeof StatusEnum;
 
+/** pet status in the store */
 export enum StatusEnum2 {
   'available' = 'available',
   'pending' = 'pending',

test/__snapshots__/common/测试 number类型 枚举.snap

@@ -154,6 +154,7 @@ export type CityGetRes = {
 };
 
 export type CityPutRes = {
+  /** Poi2CategoryEnum poi2分类 */
   city: Poi2CategoryEnum;
 };
 
@@ -162,6 +163,7 @@ export type HTTPValidationError = {
   detail?: ValidationError[];
 };
 
+/** poi2分类 */
 export enum Poi2CategoryEnum {
   'STRING_NUMBER_-1' = '-1',
   'STRING_NUMBER_-1000' = '-1000',

test/__snapshots__/common/测试 number类型 枚举，使用 desc 解析枚举.snap

@@ -35,6 +35,7 @@ export type ResultOutputUserInfoOutput = {
   data?: UserInfoOutput;
 };
 
+/** 系统用户角色:User(普通用户)=0,Agent(经纪人)=1,Admin(管理员)=2 */
 export enum SysUserRole {
   User = 0,
   Agent = 1,
@@ -50,6 +51,7 @@ export type UserInfoOutput = {
   avatar?: string;
   /** 手机号 */
   phone?: string;
+  /** 系统用户角色:User(普通用户)=0,Agent(经纪人)=1,Admin(管理员)=2 */
   role?: SysUserRole;
 };
 /* eslint-disable */