feat: jsdoc block tags (orval-labs#1231)

Marfyy · Feb 22, 2024 · 15e9033 · 15e9033
1 parent 4f95efb
commit 15e9033
Show file tree

Hide file tree

Showing 7 changed files with 151 additions and 15 deletions.
diff --git a/packages/core/src/utils/doc.ts b/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';

diff --git a/samples/basic/api/endpoints/petstoreFromFileSpec.ts b/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[];
 
 /**

diff --git a/samples/basic/api/endpoints/petstoreFromFileSpecWithConfig.ts b/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[];
 
 /**

diff --git a/samples/basic/api/endpoints/petstoreFromFileSpecWithTransformer.ts b/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(),

diff --git a/samples/basic/api/model/pet.ts b/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;
 }
diff --git a/samples/basic/api/model/pets.ts b/samples/basic/api/model/pets.ts
@@ -6,4 +6,8 @@
  */
 import type { Pet } from './pet';
 
+/**
+ * @minItems 1
+ * @maxItems 20
+ */
 export type Pets = Pet[];
diff --git a/samples/basic/petstore.yaml b/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: