feat: jsdoc block tags (#1231)

Author: martinsafsten

packages/core/src/utils/doc.ts

@@ -8,10 +8,30 @@ export function jsDoc(
     description,
     deprecated,
     summary,
+    minLength,
+    maxLength,
+    minimum,
+    maximum,
+    exclusiveMinimum,
+    exclusiveMaximum,
+    minItems,
+    maxItems,
+    nullable,
+    pattern,
   }: {
     description?: string[] | string;
     deprecated?: boolean;
     summary?: string;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: boolean;
+    exclusiveMaximum?: boolean;
+    minItems?: number;
+    maxItems?: number;
+    nullable?: boolean;
+    pattern?: string;
   },
   tryOneLine = false,
 ): string {
@@ -22,10 +42,21 @@ export function jsDoc(
       : [description || '']
   ).map((line) => line.replace(regex, replacement));
 
-  const count = [description, deprecated, summary].reduce(
-    (acc, it) => (it ? acc + 1 : acc),
-    0,
-  );
+  const count = [
+    description,
+    deprecated,
+    summary,
+    minLength?.toString(),
+    maxLength?.toString(),
+    minimum?.toString(),
+    maximum?.toString(),
+    exclusiveMinimum?.toString(),
+    exclusiveMaximum?.toString(),
+    minItems?.toString(),
+    maxItems?.toString(),
+    nullable?.toString(),
+    pattern,
+  ].reduce((acc, it) => (it ? acc + 1 : acc), 0);
 
   if (!count) {
     return '';
@@ -46,20 +77,46 @@ export function jsDoc(
     doc += ` ${lines.join('\n * ')}`;
   }
 
-  if (deprecated) {
+  function appendPrefix() {
     if (!oneLine) {
       doc += `\n${tryOneLine ? '  ' : ''} *`;
     }
-    doc += ' @deprecated';
   }
 
-  if (summary) {
-    if (!oneLine) {
-      doc += `\n${tryOneLine ? '  ' : ''} *`;
+  function tryAppendStringDocLine(key: string, value?: string) {
+    if (value) {
+      appendPrefix();
+      doc += ` @${key} ${value}`;
+    }
+  }
+
+  function tryAppendBooleanDocLine(key: string, value?: boolean) {
+    if (value === true) {
+      appendPrefix();
+      doc += ` @${key}`;
+    }
+  }
+
+  function tryAppendNumberDocLine(key: string, value?: number) {
+    if (value !== undefined) {
+      appendPrefix();
+      doc += ` @${key} ${value}`;
     }
-    doc += ` @summary ${summary.replace(regex, replacement)}`;
   }
 
+  tryAppendBooleanDocLine('deprecated', deprecated);
+  tryAppendStringDocLine('summary', summary?.replace(regex, replacement));
+  tryAppendNumberDocLine('minLength', minLength);
+  tryAppendNumberDocLine('maxLength', maxLength);
+  tryAppendNumberDocLine('minimum', minimum);
+  tryAppendNumberDocLine('maximum', maximum);
+  tryAppendBooleanDocLine('exclusiveMinimum', exclusiveMinimum);
+  tryAppendBooleanDocLine('exclusiveMaximum', exclusiveMaximum);
+  tryAppendNumberDocLine('minItems', minItems);
+  tryAppendNumberDocLine('maxItems', maxItems);
+  tryAppendBooleanDocLine('nullable', nullable);
+  tryAppendStringDocLine('pattern', pattern);
+
   doc += !oneLine ? `\n ${tryOneLine ? '  ' : ''}` : ' ';
 
   doc += '*/\n';

samples/basic/api/endpoints/petstoreFromFileSpec.ts

@@ -24,11 +24,31 @@ export interface Error {
 }
 
 export interface Pet {
+  /**
+   * @minimum 0
+   * @maximum 30
+   * @exclusiveMinimum
+   * @exclusiveMaximum
+   */
+  age?: number;
   id: number;
+  /**
+   * Name of pet
+   * @minLength 40
+   * @maxLength 0
+   */
   name: string;
-  tag?: string;
+  /**
+   * @nullable
+   * @pattern ^\\d{3}-\\d{2}-\\d{4}$
+   */
+  tag?: string | null;
 }
 
+/**
+ * @minItems 1
+ * @maxItems 20
+ */
 export type Pets = Pet[];
 
 /**

samples/basic/api/endpoints/petstoreFromFileSpecWithConfig.ts

@@ -24,11 +24,31 @@ export interface Error {
 }
 
 export interface Pet {
+  /**
+   * @minimum 0
+   * @maximum 30
+   * @exclusiveMinimum
+   * @exclusiveMaximum
+   */
+  age?: number;
   id: number;
+  /**
+   * Name of pet
+   * @minLength 40
+   * @maxLength 0
+   */
   name: string;
-  tag?: string;
+  /**
+   * @nullable
+   * @pattern ^\\d{3}-\\d{2}-\\d{4}$
+   */
+  tag?: string | null;
 }
 
+/**
+ * @minItems 1
+ * @maxItems 20
+ */
 export type Pets = Pet[];
 
 /**

samples/basic/api/endpoints/petstoreFromFileSpecWithTransformer.ts

@@ -58,13 +58,17 @@ export const getListPetsResponseMock = (overrideResponse: any = {}): Pets =>
     { length: faker.number.int({ min: 1, max: 10 }) },
     (_, i) => i + 1,
   ).map(() => ({
+    age: faker.helpers.arrayElement([
+      faker.number.int({ min: 0, max: 30 }),
+      undefined,
+    ]),
     id: faker.number.int({ min: undefined, max: undefined }),
     name: 'jon',
-    tag: 'jon',
+    tag: faker.helpers.arrayElement(['jon', null]),
     ...overrideResponse,
   }));
 
-export const getShowPetByIdResponseMock = (): Pet =>
+export const getShowPetByIdResponseMock = () =>
   (() => ({
     id: faker.number.int({ min: 1, max: 99 }),
     name: faker.person.firstName(),

samples/basic/api/model/pet.ts

@@ -6,7 +6,23 @@
  */
 
 export interface Pet {
+  /**
+   * @minimum 0
+   * @maximum 30
+   * @exclusiveMinimum
+   * @exclusiveMaximum
+   */
+  age?: number;
   id: number;
+  /**
+   * Name of pet
+   * @minLength 40
+   * @maxLength 0
+   */
   name: string;
-  tag?: string;
+  /**
+   * @nullable
+   * @pattern ^\\d{3}-\\d{2}-\\d{4}$
+   */
+  tag?: string | null;
 }

samples/basic/api/model/pets.ts

@@ -6,4 +6,8 @@
  */
 import type { Pet } from './pet';
 
+/**
+ * @minItems 1
+ * @maxItems 20
+ */
 export type Pets = Pet[];

samples/basic/petstore.yaml

@@ -111,10 +111,25 @@ components:
           format: int64
         name:
           type: string
+          description: 'Name of pet'
+          maxLength: 0
+          minLength: 40
+        age:
+          type: integer
+          format: int32
+          minimum: 0
+          maximum: 30
+          exclusiveMinimum: true
+          exclusiveMaximum: true
         tag:
           type: string
+          pattern: '^\\d{3}-\\d{2}-\\d{4}$'
+          nullable: true
+
     Pets:
       type: array
+      minItems: 1
+      maxItems: 20
       items:
         $ref: '#/components/schemas/Pet'
     Error: