feat: enhance type generation with descriptions and deprecation notices

This commit updates the type generation logic in both the schema and client generators to include JSDoc comments for properties. It adds support for descriptions and deprecation notices, improving the clarity and documentation of generated TypeScript types. The `getTypeFromSchema` function is utilized to ensure consistent handling of these attributes across different parameter types.

Author: owinter86

src/generator/clientGenerator.ts

@@ -1,12 +1,5 @@
 import type { OpenAPIV3 } from "openapi-types";
-import {
-	camelCase,
-	getTypeFromSchema,
-	pascalCase,
-	sanitizePropertyName,
-	sanitizeTypeName,
-	specTitle,
-} from "../utils";
+import { camelCase, pascalCase, sanitizeTypeName, specTitle } from "../utils";
 
 export interface OperationInfo {
 	method: string;
@@ -93,35 +86,10 @@ function generateAxiosMethod(operation: OperationInfo, spec: OpenAPIV3.Document)
 
 	const requestBodySchema = content ? resolveSchema(content, spec) : undefined;
 
-	// Build data type parts
-	const dataProps: string[] = [];
-
-	// Add path and query parameters
-	urlParams.forEach((p) => {
-		const safeName = sanitizePropertyName(p.name);
-		dataProps.push(`${safeName}: ${getTypeFromSchema(p.schema)}`);
-	});
-	queryParams.forEach((p) => {
-		const safeName = sanitizePropertyName(p.name);
-		dataProps.push(`${safeName}${p.required ? "" : "?"}: ${getTypeFromSchema(p.schema)}`);
-	});
-
 	// Add request body type if it exists
 	const hasData = (parameters && parameters.length > 0) || operation.requestBody;
 
-	let dataType = "undefined";
 	const namedType = pascalCase(operationId);
-	if (hasData) {
-		if (requestBody && dataProps.length > 0) {
-			dataType = `T.${namedType}Request & { ${dataProps.join("; ")} }`;
-		} else if (requestBody) {
-			dataType = `T.${namedType}Request`;
-		} else if (dataProps.length > 0) {
-			dataType = `{ ${dataProps.join("; ")} }`;
-		} else {
-			dataType = "Record<string, never>";
-		}
-	}
 
 	// Get response type from 2xx response
 

src/generator/schemaGenerator.ts

@@ -91,13 +91,27 @@ export function generateTypeDefinitions(spec: OpenAPIV3.Document): string {
 				// Add path and query parameters
 				urlParams.forEach((p) => {
 					const safeName = sanitizePropertyName(p.name);
-					dataProps.push(`${safeName}: ${getTypeFromSchema(p.schema)}`);
+					const isDeprecated = "deprecated" in p && p.deprecated;
+					const hasDescription = "description" in p && p.description;
+					const desc =
+						hasDescription || isDeprecated
+							? `/**${hasDescription ? `\n* ${p.description}` : ""}${isDeprecated ? "\n* @deprecated" : ""}
+							*/\n`
+							: "";
+					dataProps.push(`${desc}${safeName}: ${getTypeFromSchema(p.schema)}`);
 				});
+
 				queryParams.forEach((p) => {
 					const safeName = sanitizePropertyName(p.name);
-					dataProps.push(`${safeName}${p.required ? "" : "?"}: ${getTypeFromSchema(p.schema)}`);
+					const isDeprecated = "deprecated" in p && p.deprecated;
+					const hasDescription = "description" in p && p.description;
+					const desc =
+						hasDescription || isDeprecated
+							? `\n/**${hasDescription ? `\n* ${p.description}` : ""}${isDeprecated ? "\n* @deprecated" : ""}
+							*/\n`
+							: "";
+					dataProps.push(`${desc}${safeName}${p.required ? "" : "?"}: ${getTypeFromSchema(p.schema)}`);
 				});
-
 				// Add request body type if it exists
 				const hasData = (parameters && parameters.length > 0) || requestBody;
 

src/utils.ts

@@ -126,7 +126,14 @@ export function getTypeFromSchema(
 							const isRequired = schema.required?.includes(key);
 							const propertyType = getTypeFromSchema(prop);
 							const safeName = sanitizePropertyName(key);
-							return `  ${safeName}${isRequired ? "" : "?"}: ${propertyType};`;
+							const isDeprecated = "deprecated" in prop && prop.deprecated;
+							const hasDescription = "description" in prop && prop.description;
+							const desc =
+								hasDescription || isDeprecated
+									? `/**${hasDescription ? `\n* ${prop.description}` : ""}${isDeprecated ? "\n* @deprecated" : ""}
+									*/\n`
+									: "";
+							return `${desc}${safeName}${isRequired ? "" : "?"}: ${propertyType};`;
 						})
 						.join("\n");
 					return `{${properties}\n}${nullable}`;