fix: configure jsdoc generation for API Client Errors, add protected where necessary

mdevils · mdevils · commit ff1f9f0ce954 · 2024-06-21T14:53:54.000+02:00
diff --git a/docs/interfaces/openapi_client.OpenApiClientGeneratorConfigClient.md b/docs/interfaces/openapi_client.OpenApiClientGeneratorConfigClient.md
@@ -14,9 +14,11 @@ Configuration for generating the client.
 - [errorClassName](openapi_client.OpenApiClientGeneratorConfigClient.md#errorclassname)
 - [exportErrorClass](openapi_client.OpenApiClientGeneratorConfigClient.md#exporterrorclass)
 - [exportModels](openapi_client.OpenApiClientGeneratorConfigClient.md#exportmodels)
+- [exportOptionsType](openapi_client.OpenApiClientGeneratorConfigClient.md#exportoptionstype)
 - [exportServices](openapi_client.OpenApiClientGeneratorConfigClient.md#exportservices)
 - [filename](openapi_client.OpenApiClientGeneratorConfigClient.md#filename)
 - [filenameFormat](openapi_client.OpenApiClientGeneratorConfigClient.md#filenameformat)
+- [generateErrorJsDoc](openapi_client.OpenApiClientGeneratorConfigClient.md#generateerrorjsdoc)
 - [generateJsDoc](openapi_client.OpenApiClientGeneratorConfigClient.md#generatejsdoc)
 - [includeServices](openapi_client.OpenApiClientGeneratorConfigClient.md#includeservices)
 - [name](openapi_client.OpenApiClientGeneratorConfigClient.md#name)
@@ -69,6 +71,20 @@ Whether to export models from the client file.
 
 ___
 
+### exportOptionsType
+
+• `Optional` **exportOptionsType**: `boolean`
+
+Whether to export the client constructor options type.
+
+**`Default`**
+
+```ts
+true
+```
+
+___
+
 ### exportServices
 
 • `Optional` **exportServices**: ``"all"`` \| ``"none"`` \| \{ `services`: `string`[]  }
@@ -105,6 +121,14 @@ Filename format for the client class. Ignored if `filename` is set.
 
 ___
 
+### generateErrorJsDoc
+
+• `Optional` **generateErrorJsDoc**: `GenerateClientErrorJsDoc`
+
+Client error class JSDoc generation callback.
+
+___
+
 ### generateJsDoc
 
 • `Optional` **generateJsDoc**: [`GenerateClientJsDoc`](../modules/openapi_client.md#generateclientjsdoc)
diff --git a/src/schema-to-typescript/common.ts b/src/schema-to-typescript/common.ts
@@ -8,6 +8,7 @@ import {
     Identifier,
     identifier,
     isValidIdentifier,
+    Noop,
     nullLiteral,
     NumericLiteral,
     numericLiteral,
@@ -34,7 +35,8 @@ import {
     tsTypeLiteral,
     tsTypeReference,
     tsUnionType,
-    tsUnknownKeyword
+    tsUnknownKeyword,
+    TypeAnnotation
 } from '@babel/types';
 import {OpenApiClientGeneratorConfig} from './openapi-to-typescript-client';
 import {
@@ -317,7 +319,10 @@ export function isNamedSchema(schema: OpenApiSchema): schema is OpenApiExpandedS
     return typeof schema !== 'boolean' && schema.name !== undefined;
 }
 
-export function attachTypeAnnotation(node: Identifier, typeAnnotation: TSTypeAnnotation): Identifier {
+export function attachTypeAnnotation<T extends {typeAnnotation?: TypeAnnotation | TSTypeAnnotation | Noop | null}>(
+    node: T,
+    typeAnnotation: TSTypeAnnotation
+): T {
     node.typeAnnotation = typeAnnotation;
     return node;
 }
diff --git a/src/schema-to-typescript/common/client.ts b/src/schema-to-typescript/common/client.ts
@@ -34,6 +34,7 @@ import {generateOperationMethods} from './operation-methods';
 import {GeneratedServicesImportInfo} from './services';
 import {OpenApiInfo, OpenApiServer} from '../../schemas/common';
 import {OpenApiPaths} from '../../schemas/openapi';
+import {makeProtected} from '../../utils/ast';
 import {
     addDependencyImport,
     DependencyImports,
@@ -67,8 +68,10 @@ export function generateClient({
         exportModels,
         exportServices,
         exportErrorClass,
+        exportOptionsType,
         errorClassName,
         generateJsDoc,
+        generateErrorJsDoc,
         ...filenameConfig
     },
     generatedServiceImports,
@@ -107,41 +110,47 @@ export function generateClient({
     const clientPropertyName = 'client';
     const commonHttpClientImportName = 'commonHttpClient';
     const {importPath: clientImportPath, filename} = getFilenameAndImportPath(name, filenameConfig);
-    const clientProperty = classProperty(identifier(clientPropertyName));
-    clientProperty.typeAnnotation = tsTypeAnnotation(
-        tsTypeReference(tsQualifiedName(identifier(commonHttpClientImportName), identifier(commonHttpClientClassName)))
-    );
-
     const errorTypeName = errorClassName ?? `${name}Error`;
     const additionalTypeStatements: Statement[] = [];
     const errorClassDeclaration = classDeclaration(
         identifier(errorTypeName),
         memberExpression(identifier(commonHttpClientImportName), identifier(commonHttpClientErrorClassName)),
         classBody([classProperty(identifier('name'), stringLiteral(errorTypeName))])
     );
-    if (exportErrorClass !== false) {
-        additionalTypeStatements.push(exportNamedDeclaration(errorClassDeclaration));
-    } else {
-        additionalTypeStatements.push(errorClassDeclaration);
-    }
+    const errorClassSuggestedJsDoc: JsDocBlock = {title: `Error class for ${info.summary}`, tags: []};
+    additionalTypeStatements.push(
+        attachJsDocComment(
+            exportErrorClass !== false ? exportNamedDeclaration(errorClassDeclaration) : errorClassDeclaration,
+            renderJsDoc(
+                generateErrorJsDoc
+                    ? generateErrorJsDoc({suggestedJsDoc: errorClassSuggestedJsDoc, info})
+                    : errorClassSuggestedJsDoc,
+                jsDocRenderConfig
+            )
+        )
+    );
 
     const clientClassBody = classBody([
-        classProperty(
-            identifier(clientPropertyName),
-            newExpression(
-                memberExpression(identifier(commonHttpClientImportName), identifier(commonHttpClientClassName)),
-                [
-                    objectExpression([
-                        objectProperty(identifier('baseUrl'), stringLiteral(servers[0]?.url ?? defaultServerUrl)),
-                        objectProperty(identifier('binaryResponseType'), stringLiteral(responseBinaryType)),
-                        objectProperty(identifier('errorClass'), identifier(errorTypeName))
-                    ])
-                ]
+        makeProtected(
+            classProperty(
+                identifier(clientPropertyName),
+                newExpression(
+                    memberExpression(identifier(commonHttpClientImportName), identifier(commonHttpClientClassName)),
+                    [
+                        objectExpression([
+                            objectProperty(identifier('baseUrl'), stringLiteral(servers[0]?.url ?? defaultServerUrl)),
+                            objectProperty(identifier('binaryResponseType'), stringLiteral(responseBinaryType)),
+                            objectProperty(identifier('errorClass'), identifier(errorTypeName))
+                        ])
+                    ]
+                )
             )
         ),
-        classProperty(
-            identifier('getClient'),
-            arrowFunctionExpression([], memberExpression(thisExpression(), identifier(clientPropertyName)))
+        makeProtected(
+            classProperty(
+                identifier('getClient'),
+                arrowFunctionExpression([], memberExpression(thisExpression(), identifier(clientPropertyName)))
+            )
         )
     ]);
     const dependencyImports: DependencyImports = {};
@@ -186,23 +195,23 @@ export function generateClient({
     }
 
     const optionsTypeName = `${name}Options`;
-    const optionsTypeExport = exportNamedDeclaration(
-        tsTypeAliasDeclaration(
-            identifier(optionsTypeName),
-            null,
-            tsTypeReference(
-                identifier('Partial'),
-                tsTypeParameterInstantiation([
-                    tsTypeReference(
-                        tsQualifiedName(
-                            identifier(commonHttpClientImportName),
-                            identifier(commonHttpClientClassOptionsName)
-                        )
+    const optionsTypeDeclaration = tsTypeAliasDeclaration(
+        identifier(optionsTypeName),
+        null,
+        tsTypeReference(
+            identifier('Partial'),
+            tsTypeParameterInstantiation([
+                tsTypeReference(
+                    tsQualifiedName(
+                        identifier(commonHttpClientImportName),
+                        identifier(commonHttpClientClassOptionsName)
                     )
-                ])
-            )
+                )
+            ])
         )
     );
+    const optionsTypeStatement =
+        exportOptionsType === false ? optionsTypeDeclaration : exportNamedDeclaration(optionsTypeDeclaration);
 
     const generatedMethods = generateOperationMethods({
         paths,
@@ -260,13 +269,15 @@ export function generateClient({
 
     if (generatedMethods.validationStatements.length > 0) {
         clientClassBody.body.push(
-            classMethod(
-                'method',
-                identifier('initialize'),
-                [],
-                blockStatement(generatedMethods.validationStatements),
-                false,
-                true
+            makeProtected(
+                classMethod(
+                    'method',
+                    identifier('initialize'),
+                    [],
+                    blockStatement(generatedMethods.validationStatements),
+                    false,
+                    true
+                )
             )
         );
     }
@@ -350,7 +361,7 @@ export function generateClient({
                     stringLiteral(getRelativeImportPath(clientImportPath, commonHttpClientImportPath))
                 ),
                 ...generateTsImports(dependencyImports),
-                optionsTypeExport,
+                optionsTypeStatement,
                 ...additionalTypeStatements,
                 clientClass,
                 ...otherStatements,
diff --git a/src/schema-to-typescript/common/services.ts b/src/schema-to-typescript/common/services.ts
@@ -16,6 +16,7 @@ import {
 import {GetModelData} from './models';
 import {generateOperationMethods} from './operation-methods';
 import {openApiHttpMethods, OpenApiPaths, OpenApiTag} from '../../schemas/openapi';
+import {makeProtected} from '../../utils/ast';
 import {generateTsImports} from '../../utils/dependencies';
 import {attachJsDocComment, JsDocBlock, JsDocRenderConfig, renderJsDoc} from '../../utils/jsdoc';
 import {getRelativeImportPath} from '../../utils/paths';
@@ -142,13 +143,15 @@ export function generateServices({
 
         if (serviceMethods.validationStatements.length > 0) {
             serviceClassBody.body.push(
-                classMethod(
-                    'method',
-                    identifier('initialize'),
-                    [],
-                    blockStatement(serviceMethods.validationStatements),
-                    false,
-                    true
+                makeProtected(
+                    classMethod(
+                        'method',
+                        identifier('initialize'),
+                        [],
+                        blockStatement(serviceMethods.validationStatements),
+                        false,
+                        true
+                    )
                 )
             );
         }
diff --git a/src/schema-to-typescript/openapi-to-typescript-client.ts b/src/schema-to-typescript/openapi-to-typescript-client.ts
@@ -511,6 +511,28 @@ export type GenerateClientJsDoc = (params: {
     info: OpenApiInfo;
 }) => JsDocBlock;
 
+/**
+ * Callback for generating the JSDoc of a client.
+ *
+ * @example
+ *     function generateClientErrorJsDoc({suggestedJsDoc, info}) {
+ *         return {
+ *             ...suggestedJsDoc,
+ *             title: 'Error Class for ' + info.summary
+ *         };
+ *     }
+ */
+export type GenerateClientErrorJsDoc = (params: {
+    /**
+     * Suggested JSDoc block. Used by default if the callback is not specified.
+     */
+    suggestedJsDoc: JsDocBlock;
+    /**
+     * OpenAPI Info Object.
+     */
+    info: OpenApiInfo;
+}) => JsDocBlock;
+
 /**
  * What needs to be imported from the external source.
  */
@@ -715,10 +737,20 @@ export interface OpenApiClientGeneratorConfigClient {
      * @default true
      */
     exportErrorClass?: boolean;
+    /**
+     * Whether to export the client constructor options type.
+     *
+     * @default true
+     */
+    exportOptionsType?: boolean;
     /**
      * Client JSDoc generation callback.
      */
     generateJsDoc?: GenerateClientJsDoc;
+    /**
+     * Client error class JSDoc generation callback.
+     */
+    generateErrorJsDoc?: GenerateClientErrorJsDoc;
 }
 
 /**
diff --git a/src/utils/ast.ts b/src/utils/ast.ts
@@ -0,0 +1,6 @@
+import {ClassMethod, ClassProperty} from '@babel/types';
+
+export function makeProtected(entity: ClassProperty | ClassMethod) {
+    entity.accessibility = 'protected';
+    return entity;
+}
