diff --git a/.changeset/wild-badgers-retire.md b/.changeset/wild-badgers-retire.md new file mode 100644 index 000000000..4e87f706e --- /dev/null +++ b/.changeset/wild-badgers-retire.md @@ -0,0 +1,5 @@ +--- +"swagger-typescript-api": patch +--- + +added support of x-enum-descriptions property diff --git a/src/configuration.ts b/src/configuration.ts index 8824268fe..1810bae25 100644 --- a/src/configuration.ts +++ b/src/configuration.ts @@ -289,13 +289,33 @@ export class CodeGenConfig { */ EnumField: (key: unknown, value: unknown) => `${key} = ${value}`, /** + * /\** description \*\/ + */ + EnumFieldDescription: (description: any) => { + if (description) { + return ` /** ${description} */`; + } else { + return ""; + } + }, + /** + * /\** $A0.description \*\/ * $A0.key = $A0.value, + * /\** $A1.description \*\/ * $A1.key = $A1.value, + * /\** $AN.description \*\/ * $AN.key = $AN.value, */ EnumFieldsWrapper: (contents: Record[]) => lodash - .map(contents, ({ key, value }) => ` ${this.Ts.EnumField(key, value)}`) + .map(contents, ({ key, value, description }) => { + return [ + this.Ts.EnumFieldDescription(description), + ` ${this.Ts.EnumField(key, value)}`, + ] + .filter(Boolean) + .join("\n"); + }) .join(",\n"), /** * {\n $A \n} diff --git a/src/schema-parser/base-schema-parsers/enum.ts b/src/schema-parser/base-schema-parsers/enum.ts index 5f53f6a58..16e8a4a59 100644 --- a/src/schema-parser/base-schema-parsers/enum.ts +++ b/src/schema-parser/base-schema-parsers/enum.ts @@ -63,6 +63,8 @@ export class EnumSchemaParser extends MonoSchemaParser { const keyType = this.schemaUtils.getSchemaType(this.schema); const enumNames = this.schemaUtils.getEnumNames(this.schema); + const enumDescriptions = this.schemaUtils.getEnumDescriptions(this.schema); + let content = null; const formatValue = (value) => { @@ -96,6 +98,7 @@ export class EnumSchemaParser extends MonoSchemaParser { key: formattedKey, type: this.config.Ts.Keyword.String, value: this.config.Ts.StringValue(enumName), + description: enumDescriptions?.[index], }; } @@ -103,15 +106,17 @@ export class EnumSchemaParser extends MonoSchemaParser { key: formattedKey, type: keyType, value: formatValue(enumValue), + description: enumDescriptions?.[index], }; }); } else { - content = this.schema.enum.map((value) => { + content = this.schema.enum.map((value, index) => { return { // @ts-expect-error TS(2345) FIXME: Argument of type '{ value: any; }' is not assignab... Remove this comment to see the full error message key: this.formatEnumKey({ value }), type: keyType, value: formatValue(value), + description: enumDescriptions?.[index], }; }); } diff --git a/src/schema-parser/schema-utils.ts b/src/schema-parser/schema-utils.ts index 7c344687b..b731c8bb9 100644 --- a/src/schema-parser/schema-utils.ts +++ b/src/schema-parser/schema-utils.ts @@ -44,6 +44,15 @@ export class SchemaUtils { ); }; + getEnumDescriptions = (schema) => { + return ( + schema["x-enumDescriptions"] || + schema.xEnumDescriptions || + schema["x-enumdescriptions"] || + schema["x-enum-descriptions"] + ); + }; + getSchemaRefType = (schema) => { if (!this.isRefSchema(schema)) return null; return this.schemaComponentsMap.get(schema.$ref); diff --git a/templates/base/enum-data-contract.ejs b/templates/base/enum-data-contract.ejs index 56107460b..e46050cb9 100644 --- a/templates/base/enum-data-contract.ejs +++ b/templates/base/enum-data-contract.ejs @@ -7,6 +7,12 @@ const { name, $content } = contract; export type <%~ name %> = <%~ _.map($content, ({ value }) => value).join(" | ") %> <% } else { %> export enum <%~ name %> { - <%~ _.map($content, ({ key, value }) => `${key} = ${value}`).join(",\n") %> + <%~ _.map($content, ({ key, value, description }) => { + let formattedDescription = description && formatDescription(description, true); + return [ + formattedDescription && `/** ${formattedDescription} */`, + `${key} = ${value}` + ].filter(Boolean).join("\n"); + }).join(",\n") %> } <% } %> diff --git a/tests/spec/enumIncludesNumber/__snapshots__/basic.test.ts.snap b/tests/spec/enumIncludesNumber/__snapshots__/basic.test.ts.snap index 2542a62e7..571ebdb11 100644 --- a/tests/spec/enumIncludesNumber/__snapshots__/basic.test.ts.snap +++ b/tests/spec/enumIncludesNumber/__snapshots__/basic.test.ts.snap @@ -14,8 +14,11 @@ exports[`basic > use x-enumNames as the key for enum 1`] = ` */ export enum StringEnumIncludesNumbersAndUnderscore { + /** Foo */ VAL_1 = "VAL_1", + /** Bar */ VAL_2 = "VAL_2", + /** Baz */ VAL_3 = "VAL_3", _1_VAL = "_1_VAL", A_1_B_2_C_3 = "A_1_B_2_C_3", diff --git a/tests/spec/enumIncludesNumber/schema.json b/tests/spec/enumIncludesNumber/schema.json index 40ae9f46d..324298f10 100644 --- a/tests/spec/enumIncludesNumber/schema.json +++ b/tests/spec/enumIncludesNumber/schema.json @@ -14,7 +14,8 @@ "A_1_B_2_C_3", "_A_1_B_2_C_3", "_1_A_2_B_3_C" - ] + ], + "x-enum-descriptions": ["Foo", "Bar", "Baz"] } } }