Feature implementation from commits f0672b5..6ee8b2f

README.md

@@ -71,6 +71,7 @@ Options:
   --implicit-required               When true, will make all properties of an object required by default (rather than the current opposite), unless an explicitly `required` array is set
   --with-deprecated                 when true, will keep deprecated endpoints in the api output
   --with-description                when true, will add z.describe(xxx)
+  --with-docs                       when true, will add jsdoc comments to generated types 
   --group-strategy                  groups endpoints by a given strategy, possible values are: 'none' | 'tag' | 'method' | 'tag-file' | 'method-file'
   --complexity-threshold            schema complexity threshold to determine which one (using less than `<` operator) should be assigned to a variable
   --default-status                  when defined as `auto-correct`, will automatically use `default` as fallback for `response` when no status code was declared

lib/CHANGELOG.md

@@ -1,5 +1,29 @@
 # openapi-zod-client
 
+## 1.18.0
+
+### Minor Changes
+
+-   [#275](https://github.com/astahmer/openapi-zod-client/pull/275) [`ed50076`](https://github.com/astahmer/openapi-zod-client/commit/ed500762c6998fb2976e8ad43a88a3a09d928f2c) Thanks [@senecolas](https://github.com/senecolas)! - Add `withDocs` option and `--with-docs` flag that adds JSDoc to generated code
+
+## 1.17.0
+
+### Minor Changes
+
+-   [#283](https://github.com/astahmer/openapi-zod-client/pull/283) [`3ec4915`](https://github.com/astahmer/openapi-zod-client/commit/3ec491572e56fc40e3b49cefb58cb6f08600190f) Thanks [@dgadelha](https://github.com/dgadelha)! - Add `schemaRefiner` option to allow refining the OpenAPI schema before its converted to a Zod schema
+
+## 1.16.4
+
+### Patch Changes
+
+-   [#279](https://github.com/astahmer/openapi-zod-client/pull/279) [`f3ee25e`](https://github.com/astahmer/openapi-zod-client/commit/f3ee25efc191d0be97231498924fe50fd977fb88) Thanks [@dgadelha](https://github.com/dgadelha)! - Fix multiline descriptions when `describe` is enabled
+
+## 1.16.3
+
+### Patch Changes
+
+-   [#276](https://github.com/astahmer/openapi-zod-client/pull/276) [`aa4c7a3`](https://github.com/astahmer/openapi-zod-client/commit/aa4c7a3668c6d96492bcd319ccd940f0b735b029) Thanks [@tankers746](https://github.com/tankers746)! - Fixed bug which was excluding falsy default values
+
 ## 1.16.2
 
 ### Patch Changes

lib/package.json

@@ -1,6 +1,6 @@
 {
     "name": "openapi-zod-client",
-    "version": "1.16.2",
+    "version": "1.18.0",
     "repository": {
         "type": "git",
         "url": "https://github.com/astahmer/openapi-zod-client.git"

lib/src/cli.ts

@@ -37,6 +37,7 @@ cli.command("<input>", "path/url to OpenAPI/Swagger document as json/yaml")
     )
     .option("--with-deprecated", "when true, will keep deprecated endpoints in the api output")
     .option("--with-description", "when true, will add z.describe(xxx)")
+    .option("--with-docs", "when true, will add jsdoc comments to generated types")
     .option(
         "--group-strategy",
         "groups endpoints by a given strategy, possible values are: 'none' | 'tag' | 'method' | 'tag-file' | 'method-file'"
@@ -85,6 +86,7 @@ cli.command("<input>", "path/url to OpenAPI/Swagger document as json/yaml")
                 isMediaTypeAllowed: options.mediaTypeExpr,
                 withImplicitRequiredProps: options.implicitRequired,
                 withDeprecatedEndpoints: options.withDeprecated,
+                withDocs: options.withDocs,
                 groupStrategy: options.groupStrategy,
                 complexityThreshold: options.complexityThreshold,
                 defaultStatusBehavior: options.defaultStatus,

lib/src/generateJSDocArray.ts

@@ -0,0 +1,45 @@
+import type { SchemaObject } from "openapi3-ts";
+
+export default function generateJSDocArray(schema: SchemaObject, withTypesAndFormat = false): string[] {
+    const comments: string[] = [];
+
+    const mapping = {
+        description: (value: string) => `${value}`,
+        example: (value: any) => `@example ${JSON.stringify(value)}`,
+        examples: (value: any[]) =>
+            value.map((example, index) => `@example Example ${index + 1}: ${JSON.stringify(example)}`),
+        deprecated: (value: boolean) => (value ? "@deprecated" : ""),
+        default: (value: any) => `@default ${JSON.stringify(value)}`,
+        externalDocs: (value: { url: string }) => `@see ${value.url}`,
+        // Additional attributes that depend on `withTypesAndFormat`
+        type: withTypesAndFormat
+            ? (value: string | string[]) => `@type {${Array.isArray(value) ? value.join("|") : value}}`
+            : undefined,
+        format: withTypesAndFormat ? (value: string) => `@format ${value}` : undefined,
+        minimum: (value: number) => `@minimum ${value}`,
+        maximum: (value: number) => `@maximum ${value}`,
+        minLength: (value: number) => `@minLength ${value}`,
+        maxLength: (value: number) => `@maxLength ${value}`,
+        pattern: (value: string) => `@pattern ${value}`,
+        enum: (value: string[]) => `@enum ${value.join(", ")}`,
+    };
+
+    Object.entries(mapping).forEach(([key, mappingFunction]) => {
+        const schemaValue = schema[key as keyof SchemaObject];
+        if (schemaValue !== undefined && mappingFunction) {
+            const result = mappingFunction(schemaValue);
+            if (Array.isArray(result)) {
+                result.forEach((subResult) => comments.push(subResult));
+            } else if (result) {
+                comments.push(result);
+            }
+        }
+    });
+
+    // Add a space line after description if there are other comments
+    if (comments.length > 1 && !!schema.description) {
+        comments.splice(1, 0, "");
+    }
+
+    return comments;
+}

lib/src/getZodiosEndpointDefinitionList.ts

@@ -249,7 +249,7 @@ export const getZodiosEndpointDefinitionList = (doc: OpenAPIObject, options?: Te
                     }
 
                     if (options?.withDescription && paramSchema) {
-                        (paramSchema as SchemaObject).description = (paramItem.description ?? "")?.replace("\n", "");
+                        (paramSchema as SchemaObject).description = (paramItem.description ?? "").trim();
                     }
 
                     // resolve ref if needed, and fallback to default (unknown) value if needed

lib/src/openApiToTypescript.ts

@@ -7,6 +7,7 @@ import type { DocumentResolver } from "./makeSchemaResolver";
 import type { TemplateContext } from "./template-context";
 import { wrapWithQuotesIfNeeded } from "./utils";
 import { inferRequiredSchema } from "./inferRequiredOnly";
+import generateJSDocArray from "./generateJSDocArray";
 
 type TsConversionArgs = {
     schema: SchemaObject | ReferenceObject;
@@ -155,6 +156,7 @@ TsConversionArgs): ts.Node | TypeDefinitionObject | string => {
             if (schema.allOf.length === 1) {
                 return getTypescriptFromOpenApi({ schema: schema.allOf[0]!, ctx, meta, options });
             }
+
             const { patchRequiredSchemaInLoop, noRequiredOnlyAllof, composedRequiredSchema } =
                 inferRequiredSchema(schema);
 
@@ -164,7 +166,7 @@ TsConversionArgs): ts.Node | TypeDefinitionObject | string => {
                 return type;
             });
 
-            if (Object.keys(composedRequiredSchema.properties).length) {
+            if (Object.keys(composedRequiredSchema.properties).length > 0) {
                 types.push(
                     getTypescriptFromOpenApi({
                         schema: composedRequiredSchema,
@@ -174,6 +176,7 @@ TsConversionArgs): ts.Node | TypeDefinitionObject | string => {
                     }) as TypeDefinition
                 );
             }
+
             return schema.nullable ? t.union([t.intersection(types), t.reference("null")]) : t.intersection(types);
         }
 
@@ -294,8 +297,9 @@ TsConversionArgs): ts.Node | TypeDefinitionObject | string => {
                 throw new Error("Name is required to convert an object schema to a type reference");
             }
 
-            const base = t.type(inheritedMeta.name, doWrapReadOnly(objectType));
-            if (!isPartial) return base;
+            if (!isPartial) {
+                return t.type(inheritedMeta.name, doWrapReadOnly(objectType));
+            }
 
             return t.type(inheritedMeta.name, t.reference("Partial", [doWrapReadOnly(objectType)]));
         }
@@ -305,7 +309,21 @@ TsConversionArgs): ts.Node | TypeDefinitionObject | string => {
         throw new Error(`Unsupported schema type: ${schemaType}`);
     };
 
-    const tsResult = getTs();
+    let tsResult = getTs();
+
+    // Add JSDoc comments
+    if (options?.withDocs && !isReferenceObject(schema)) {
+        const jsDocComments = generateJSDocArray(schema);
+
+        if (
+            jsDocComments.length > 0 &&
+            typeof tsResult === "object" &&
+            tsResult.kind !== ts.SyntaxKind.TypeAliasDeclaration
+        ) {
+            tsResult = t.comment(tsResult, jsDocComments);
+        }
+    }
+
     return canBeWrapped
         ? wrapTypeIfInline({ isInline, name: inheritedMeta?.name, typeDef: tsResult as TypeDefinition })
         : tsResult;

lib/src/openApiToZod.ts

@@ -20,10 +20,12 @@ type ConversionArgs = {
  * @see https://github.com/colinhacks/zod
  */
 // eslint-disable-next-line sonarjs/cognitive-complexity
-export function getZodSchema({ schema, ctx, meta: inheritedMeta, options }: ConversionArgs): CodeMeta {
-    if (!schema) {
+export function getZodSchema({ schema: $schema, ctx, meta: inheritedMeta, options }: ConversionArgs): CodeMeta {
+    if (!$schema) {
         throw new Error("Schema is required");
     }
+
+    const schema = options?.schemaRefiner?.($schema, inheritedMeta) ?? $schema;
     const code = new CodeMeta(schema, ctx, inheritedMeta);
     const meta = {
         parent: code.inherit(inheritedMeta?.parent),
@@ -302,7 +304,11 @@ export const getZodChain = ({ schema, meta, options }: ZodChainArgs) => {
         .otherwise(() => void 0);
 
     if (typeof schema.description === "string" && schema.description !== "" && options?.withDescription) {
-        chains.push(`describe("${schema.description}")`);
+        if (["\n", "\r", "\r\n"].some((c) => String.prototype.includes.call(schema.description, c))) {
+            chains.push(`describe(\`${schema.description}\`)`);
+        } else {
+            chains.push(`describe("${schema.description}")`);
+        }
     }
 
     const output = chains
@@ -341,7 +347,7 @@ const unwrapQuotesIfNeeded = (value: string | number) => {
 };
 
 const getZodChainableDefault = (schema: SchemaObject) => {
-    if (schema.default) {
+    if (schema.default !== undefined) {
         const value = match(schema.type)
             .with("number", "integer", () => unwrapQuotesIfNeeded(schema.default))
             .otherwise(() => JSON.stringify(schema.default));

lib/src/template-context.ts

@@ -1,4 +1,4 @@
-import type { OpenAPIObject, OperationObject, PathItemObject, SchemaObject } from "openapi3-ts";
+import type { OpenAPIObject, OperationObject, PathItemObject, ReferenceObject, SchemaObject } from "openapi3-ts";
 import { sortBy, sortListFromRefArray, sortObjKeysFromArray } from "pastable/server";
 import { ts } from "tanu";
 import { match } from "ts-pattern";
@@ -11,6 +11,7 @@ import { getTypescriptFromOpenApi } from "./openApiToTypescript";
 import { getZodSchema } from "./openApiToZod";
 import { topologicalSort } from "./topologicalSort";
 import { asComponentSchema, normalizeString } from "./utils";
+import type { CodeMetaData } from "./CodeMeta";
 
 const file = ts.createSourceFile("", "", ts.ScriptTarget.ESNext, true);
 const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
@@ -334,6 +335,11 @@ export type TemplateContextOptions = {
      * @default false
      */
     withDeprecatedEndpoints?: boolean;
+    /**
+     * when true, will add jsdoc comments to generated types
+     * @default false
+     */
+    withDocs?: boolean;
     /**
      * groups endpoints by a given strategy
      *
@@ -403,4 +409,9 @@ export type TemplateContextOptions = {
      * If 2 schemas have the same name but different types, export subsequent names with numbers appended
      */
     exportAllNamedSchemas?: boolean;
+
+    /**
+     * A function that runs in the schema conversion process to refine the schema before it's converted to a Zod schema.
+     */
+    schemaRefiner?: <T extends SchemaObject | ReferenceObject>(schema: T, parentMeta?: CodeMetaData) => T;
 };

lib/tests/description-in-zod.test.ts

@@ -31,6 +31,23 @@ test("description-in-zod", async () => {
                             },
                             description: "bar description",
                         },
+                        {
+                            in: "query",
+                            name: "baz",
+                            schema: {
+                                type: "number",
+                                enum: [1.3, 34.1, -57.89],
+                            },
+                            description: "baz\nmultiline\ndescription",
+                        },
+                        {
+                            in: "query",
+                            name: "qux",
+                            schema: {
+                                type: "string",
+                            },
+                            description: "      ", // spaces only description
+                        },
                     ],
                     responses: {
                         "200": {
@@ -73,6 +90,21 @@ test("description-in-zod", async () => {
                 .describe("bar description")
                 .optional(),
             },
+            {
+              name: "baz",
+              type: "Query",
+              schema: z
+                .union([z.literal(1.3), z.literal(34.1), z.literal(-57.89)])
+                .describe(
+                  \`baz\nmultiline\ndescription\`
+                )
+                .optional(),
+            },
+            {
+              name: "qux",
+              type: "Query",
+              schema: z.string().optional(),
+            },
           ],
           response: z.void(),
         },