Using const for literals in documentation (#1651)

This is not documented well on the OpenAPI website, but it's inherited from the JSON Schema validation standard. And it works: ![image](https://github.com/RobinTail/express-zod-api/assets/13189514/92e12a7a-3879-43ee-b4ab-345d7f64c930) ``` 0 problems (0 error, 0 warnings, 0 information, 0 hints) ```
RobinTail · Apr 1, 2024 · 540d58a · 540d58a
1 parent d2d9680
commit 540d58a
Show file tree

Hide file tree

Showing 6 changed files with 226 additions and 305 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,33 @@
 
 ## Version 17
 
+### v17.6.0
+
+- Using `const` property for depicting `z.literal()` in the generated documentation;
+- Fixed possibly invalid values of `type` property when depicting `z.literal()`, `z.enum()` and `z.nativeEnum()`.
+
+```yaml
+# z.literal("success")
+before:
+  type: string
+  enum: # replaced
+    - success
+after:
+  type: string
+  const: success
+```
+
+```yaml
+# z.literal(null)
+before:
+  type: object # fixed
+  enum:
+    - null
+after:
+  type: null
+  const: null
+```
+
 ### v17.5.0
 
 - Depicting the `.rest()` part of `z.tuple()` in the generated `Documentation`:

diff --git a/example/example.documentation.yaml b/example/example.documentation.yaml
@@ -29,8 +29,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - success
+                    const: success
                   data:
                     type: object
                     properties:
@@ -69,8 +68,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - error
+                    const: error
                   error:
                     type: object
                     properties:
@@ -147,8 +145,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - success
+                    const: success
                   data:
                     type: object
                     properties:
@@ -185,8 +182,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - error
+                    const: error
                   error:
                     type: object
                     properties:
@@ -230,8 +226,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - created
+                    const: created
                   data:
                     type: object
                     properties:
@@ -254,8 +249,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - created
+                    const: created
                   data:
                     type: object
                     properties:
@@ -278,8 +272,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - error
+                    const: error
                   reason:
                     type: string
                 required:
@@ -294,8 +287,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - exists
+                    const: exists
                   id:
                     type: integer
                     format: int64
@@ -313,8 +305,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - error
+                    const: error
                   reason:
                     type: string
                 required:
@@ -440,8 +431,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - success
+                    const: success
                   data:
                     type: object
                     properties:
@@ -478,8 +468,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - error
+                    const: error
                   error:
                     type: object
                     properties:
@@ -518,8 +507,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - success
+                    const: success
                   data:
                     type: object
                     properties:
@@ -542,8 +530,7 @@ paths:
                 properties:
                   status:
                     type: string
-                    enum:
-                      - error
+                    const: error
                   error:
                     type: object
                     properties:

diff --git a/src/documentation-helpers.ts b/src/documentation-helpers.ts
@@ -18,6 +18,7 @@ import {
   both,
   complement,
   concat,
+  type as detectType,
   filter,
   fromPairs,
   has,
@@ -32,6 +33,7 @@ import {
   pluck,
   range,
   reject,
+  toLower,
   union,
   when,
   xprod,
@@ -257,18 +259,34 @@ export const depictNullable: Depicter<z.ZodNullable<z.ZodTypeAny>> = ({
   return nested;
 };
 
+const getSupportedType = (value: unknown): SchemaObjectType | undefined => {
+  const detected = toLower(detectType(value)); // toLower is typed well unlike .toLowerCase()
+  const isSupported =
+    detected === "number" ||
+    detected === "string" ||
+    detected === "boolean" ||
+    detected === "object" ||
+    detected === "null" ||
+    detected === "array";
+  return typeof value === "bigint"
+    ? "integer"
+    : isSupported
+      ? detected
+      : undefined;
+};
+
 export const depictEnum: Depicter<
   z.ZodEnum<[string, ...string[]]> | z.ZodNativeEnum<any> // keeping "any" for ZodNativeEnum as compatibility fix
 > = ({ schema }) => ({
-  type: typeof Object.values(schema.enum)[0] as "string" | "number",
+  type: getSupportedType(Object.values(schema.enum)[0]),
   enum: Object.values(schema.enum),
 });
 
 export const depictLiteral: Depicter<z.ZodLiteral<unknown>> = ({
   schema: { value },
 }) => ({
-  type: typeof value as "string" | "number" | "boolean",
-  enum: [value],
+  type: getSupportedType(value), // constructor allows z.Primitive only, but ZodLiteral does not have that constrant
+  const: value,
 });
 
 export const depictObject: Depicter<z.ZodObject<z.ZodRawShape>> = ({
@@ -539,10 +557,10 @@ export const depictObjectProperties = ({
 }: Parameters<Depicter<z.ZodObject<z.ZodRawShape>>>[0]) => map(next, shape);
 
 const makeSample = (depicted: SchemaObject) => {
-  const type = (
+  const firstType = (
     Array.isArray(depicted.type) ? depicted.type[0] : depicted.type
   ) as keyof typeof samples;
-  return samples?.[type];
+  return samples?.[firstType];
 };
 
 const makeNullableType = (prev: SchemaObject): SchemaObjectType[] => {

diff --git a/tests/unit/__snapshots__/documentation-helpers.spec.ts.snap b/tests/unit/__snapshots__/documentation-helpers.spec.ts.snap
@@ -103,9 +103,7 @@ exports[`Documentation helpers > depictDiscriminatedUnion() > should wrap next d
           "format": "any",
         },
         "status": {
-          "enum": [
-            "success",
-          ],
+          "const": "success",
           "type": "string",
         },
       },
@@ -128,9 +126,7 @@ exports[`Documentation helpers > depictDiscriminatedUnion() > should wrap next d
           "type": "object",
         },
         "status": {
-          "enum": [
-            "error",
-          ],
+          "const": "error",
           "type": "string",
         },
       },
@@ -317,9 +313,7 @@ exports[`Documentation helpers > depictIntersection() > should fall back to allO
       "type": "number",
     },
     {
-      "enum": [
-        5,
-      ],
+      "const": 5,
       "type": "number",
     },
   ],
@@ -392,9 +386,7 @@ exports[`Documentation helpers > depictIntersection() > should maintain uniquene
 {
   "properties": {
     "test": {
-      "enum": [
-        5,
-      ],
+      "const": 5,
       "format": "double",
       "maximum": 1.7976931348623157e+308,
       "minimum": -1.7976931348623157e+308,
@@ -495,15 +487,34 @@ exports[`Documentation helpers > depictLazy > should handle circular references
 }
 `;
 
-exports[`Documentation helpers > depictLiteral() > should set type and involve enum property 1`] = `
+exports[`Documentation helpers > depictLiteral() > should set type and involve const property 0 1`] = `
 {
-  "enum": [
-    "testing",
-  ],
+  "const": "testng",
   "type": "string",
 }
 `;
 
+exports[`Documentation helpers > depictLiteral() > should set type and involve const property 1 1`] = `
+{
+  "const": null,
+  "type": "null",
+}
+`;
+
+exports[`Documentation helpers > depictLiteral() > should set type and involve const property 2 1`] = `
+{
+  "const": 123n,
+  "type": "integer",
+}
+`;
+
+exports[`Documentation helpers > depictLiteral() > should set type and involve const property 3 1`] = `
+{
+  "const": Symbol(test),
+  "type": undefined,
+}
+`;
+
 exports[`Documentation helpers > depictNull() > should give type:null 1`] = `
 {
   "type": "null",
@@ -1248,9 +1259,7 @@ exports[`Documentation helpers > depictTuple() > should utilize prefixItems and
       "type": "string",
     },
     {
-      "enum": [
-        "test",
-      ],
+      "const": "test",
       "type": "string",
     },
   ],