@cparra/apexdocs 2.9.0 → 2.11.0

package/src/test-helpers/SettingsBuilder.ts

@@ -16,6 +16,7 @@ export class SettingsBuilder {
       defaultGroupName: 'Misc',
       sanitizeHtml: true,
       openApiTitle: 'Apex API',
+      openApiFileName: 'openapi',
     };
   }
 }

package/src/transpiler/markdown/class-file-generatorHelper.ts

@@ -11,7 +11,8 @@ export default class ClassFileGeneratorHelper {
 
   public static getFileLink(classModel: Type) {
     const directoryRoot = this.getDirectoryRoot(classModel);
-    return `[${classModel.name}](${directoryRoot}${classModel.name}.md)`;
+    const fullClassName = `${Settings.getInstance().getNamespacePrefix()}${classModel.name}`;
+    return `[${fullClassName}](${directoryRoot}${fullClassName}.md)`;
   }
 
   public static getFileLinkByTypeName(typeName: string) {

package/src/transpiler/openapi/open-api-docs-processor.ts

@@ -18,7 +18,7 @@ export class OpenApiDocsProcessor extends ProcessorTypeTranspiler {
     if (!title) {
       throw Error('No OpenApi title was provided.');
     }
-    this.openApiModel = new OpenApi(title, '1.0.0');
+    this.openApiModel = new OpenApi(title, '1.0.0', Settings.getInstance().getNamespace());
   }
 
   fileBuilder(): FileContainer {
@@ -57,9 +57,11 @@ export class OpenApiDocsProcessor extends ProcessorTypeTranspiler {
 
     // DELETE
     parser.parseMethod(typeAsClass, endpointPath, 'delete');
+  }
 
+  onAfterProcess: ((types: Type[]) => void) | undefined = () => {
     this._fileContainer.pushFile(new OpenapiTypeFile(this.openApiModel));
-  }
+  };
 
   private getEndpointPath(type: Type): string | null {
     const restResourceAnnotation = type.annotations.find((element) => element.name.toLowerCase() === 'restresource');

package/src/transpiler/openapi/parsers/MethodParser.ts

@@ -2,7 +2,7 @@ import { ClassMirror, MethodMirror } from '@cparra/apex-reflection';
 import { OpenApi } from '../../../model/openapi/open-api';
 import * as yaml from 'js-yaml';
 import { ClassMirrorWrapper } from '../../../model/apex-type-wrappers/ClassMirrorWrapper';
-import { Reference } from './ReferenceBuilder';
+import { Reference, ReferenceBuilder } from './ReferenceBuilder';
 import { ParameterObjectBuilder } from './ParameterObjectBuilder';
 import { ResponsesBuilder } from './ResponsesBuilder';
 import {
@@ -11,8 +11,11 @@ import {
   ApexDocParameterObject,
 } from '../../../model/openapi/apex-doc-types';
 import { RequestBodyBuilder } from './RequestBodyBuilder';
+import { ApexDocSchemaAware } from './Builder';
+import { PropertiesObject, ReferenceObject } from '../../../model/openapi/open-api-types';
 
-type AddToOpenApi = (inYaml: string, urlValue: string) => void;
+type FallbackMethodParser = (methodMirror: MethodMirror) => void;
+type AddToOpenApi<T extends ApexDocSchemaAware> = (input: T, urlValue: string, httpMethodKey: HttpOperations) => void;
 
 type HttpOperations = 'get' | 'put' | 'post' | 'delete' | 'patch';
 
@@ -39,28 +42,47 @@ export class MethodParser {
       this.openApiModel.paths[httpUrlEndpoint][httpMethodKey]!.description = httpMethod.docComment.description;
     }
 
-    this.parseHttpAnnotation(httpMethod, httpUrlEndpoint, 'http-request-body', (inYaml, urlValue) =>
-      this.addRequestBodyToOpenApi(inYaml, urlValue, httpMethodKey),
+    this.parseHttpAnnotation<ApexDocHttpRequestBody>(
+      httpMethod,
+      httpUrlEndpoint,
+      httpMethodKey,
+      'http-request-body',
+      this.addRequestBodyToOpenApi.bind(this),
+      this.fallbackHttpRequestBodyParser(httpUrlEndpoint, httpMethodKey),
     );
-    this.parseHttpAnnotation(httpMethod, httpUrlEndpoint, 'http-parameter', (inYaml, urlValue) =>
-      this.addParametersToOpenApi(inYaml, urlValue, httpMethodKey),
+
+    this.parseHttpAnnotation<ApexDocParameterObject>(
+      httpMethod,
+      httpUrlEndpoint,
+      httpMethodKey,
+      'http-parameter',
+      this.addParametersToOpenApi.bind(this),
     );
-    this.parseHttpAnnotation(httpMethod, httpUrlEndpoint, 'http-response', (inYaml, urlValue) =>
-      this.addHttpResponsesToOpenApi(inYaml, urlValue, httpMethodKey),
+
+    this.parseHttpAnnotation<ApexDocHttpResponse>(
+      httpMethod,
+      httpUrlEndpoint,
+      httpMethodKey,
+      'http-response',
+      this.addHttpResponsesToOpenApi.bind(this),
+      this.getFallbackHttpResponseParser(httpUrlEndpoint, httpMethodKey),
     );
   }
 
-  private parseHttpAnnotation(
-    httpGetMethod: MethodMirror,
+  private parseHttpAnnotation<T extends ApexDocSchemaAware>(
+    httpMethod: MethodMirror,
     urlValue: string,
+    httpMethodKey: HttpOperations,
     annotationName: string,
-    addToOpenApi: AddToOpenApi,
+    addToOpenApi: AddToOpenApi<T>,
+    fallbackParser?: FallbackMethodParser,
   ) {
-    const annotations = httpGetMethod.docComment?.annotations.filter(
-      (annotation) => annotation.name === annotationName,
-    );
+    const annotations = httpMethod.docComment?.annotations.filter((annotation) => annotation.name === annotationName);
 
     if (!annotations?.length) {
+      if (fallbackParser) {
+        fallbackParser(httpMethod);
+      }
       return;
     }
 
@@ -72,46 +94,128 @@ export class MethodParser {
         return;
       }
 
-      addToOpenApi(inYaml, urlValue);
+      this.addToOpenApiStrategy<T>(inYaml, urlValue, httpMethodKey, addToOpenApi);
     }
   }
 
-  private addRequestBodyToOpenApi(inYaml: string, urlValue: string, httpMethodKey: HttpOperations) {
+  private addToOpenApiStrategy<T extends ApexDocSchemaAware>(
+    inYaml: string,
+    urlValue: string,
+    httpMethodKey: HttpOperations,
+    addToOpenApi: AddToOpenApi<T>,
+  ): void {
     // Convert the YAML into a JSON object.
-    const inJson = yaml.load(inYaml) as ApexDocHttpRequestBody;
+    const inJson = yaml.load(inYaml) as T;
     const requestBodyResponse = new RequestBodyBuilder().build(inJson);
 
-    this.openApiModel.paths[urlValue][httpMethodKey]!.requestBody = requestBodyResponse.body;
+    addToOpenApi(inJson, urlValue, httpMethodKey);
 
     this.addReference(requestBodyResponse);
   }
 
-  private addParametersToOpenApi(inYaml: string, urlValue: string, httpMethodKey: HttpOperations) {
-    // Convert the YAML into a JSON object.
-    const inJson = yaml.load(inYaml) as ApexDocParameterObject;
-    const parameterObjectResponse = new ParameterObjectBuilder().build(inJson);
+  private addRequestBodyToOpenApi(
+    input: ApexDocHttpRequestBody,
+    urlValue: string,
+    httpMethodKey: HttpOperations,
+  ): void {
+    const requestBodyResponse = new RequestBodyBuilder().build(input);
+    this.openApiModel.paths[urlValue][httpMethodKey]!.requestBody = requestBodyResponse.body;
+  }
+
+  private addParametersToOpenApi(input: ApexDocParameterObject, urlValue: string, httpMethodKey: HttpOperations): void {
+    const parameterObjectResponse = new ParameterObjectBuilder().build(input);
 
     if (this.openApiModel.paths[urlValue][httpMethodKey]!.parameters === undefined) {
       // If no parameters have been defined yet, initialize the list.
       this.openApiModel.paths[urlValue][httpMethodKey]!.parameters = [];
     }
     this.openApiModel.paths[urlValue][httpMethodKey]!.parameters!.push(parameterObjectResponse.body);
-
-    this.addReference(parameterObjectResponse);
   }
 
-  private addHttpResponsesToOpenApi(inYaml: string, urlValue: string, httpMethodKey: HttpOperations) {
-    // Convert the YAML into a JSON object.
-    const inJson = yaml.load(inYaml) as ApexDocHttpResponse;
-    const responseObjectResponse = new ResponsesBuilder().build(inJson);
+  private addHttpResponsesToOpenApi(input: ApexDocHttpResponse, urlValue: string, httpMethodKey: HttpOperations): void {
+    const responseObjectResponse = new ResponsesBuilder().build(input);
 
     if (this.openApiModel.paths[urlValue][httpMethodKey]!.responses === undefined) {
       this.openApiModel.paths[urlValue][httpMethodKey]!.responses = {};
     }
 
-    this.openApiModel.paths[urlValue][httpMethodKey]!.responses![inJson.statusCode] = responseObjectResponse.body;
+    this.openApiModel.paths[urlValue][httpMethodKey]!.responses![input.statusCode] = responseObjectResponse.body;
+  }
+
+  private fallbackHttpRequestBodyParser(
+    httpUrlEndpoint: string,
+    httpMethodKey: 'get' | 'put' | 'post' | 'delete' | 'patch',
+  ) {
+    return (methodMirror: MethodMirror) => {
+      // If the Apex method receives parameters, they will be interpreted by Salesforce as a JSON
+      // object, with each key of the object being the parameter name.
+      const parameters = methodMirror.parameters;
+
+      if (!parameters.length) {
+        return;
+      }
+
+      const propertiesObject: PropertiesObject = {};
+      parameters.forEach((currentParameter) => {
+        const propertyKey = currentParameter.name;
+        const propertyReference = new ReferenceBuilder().getReferenceType(currentParameter.typeReference);
+
+        propertiesObject[propertyKey] = propertyReference.schema;
+
+        this.addReference({
+          reference: {
+            entrypointReferenceObject: propertyReference.schema as ReferenceObject,
+            referenceComponents: propertyReference.referenceComponents,
+          },
+        });
+      });
+
+      this.openApiModel.paths[httpUrlEndpoint][httpMethodKey]!.requestBody = {
+        content: {
+          'application/json': {
+            schema: {
+              type: 'object',
+              properties: propertiesObject,
+            },
+          },
+        },
+      };
+    };
+  }
+
+  private getFallbackHttpResponseParser(
+    httpUrlEndpoint: string,
+    httpMethodKey: 'get' | 'put' | 'post' | 'delete' | 'patch',
+  ) {
+    return (methodMirror: MethodMirror) => {
+      // Parses methods that return an object (as opposed to void).
+      const returnType = methodMirror.typeReference;
+
+      if (returnType.type.toLowerCase() === 'void') {
+        return;
+      }
+
+      const reference = new ReferenceBuilder().getReferenceType(returnType);
+
+      this.addReference({
+        reference: {
+          entrypointReferenceObject: reference.schema as ReferenceObject,
+          referenceComponents: reference.referenceComponents,
+        },
+      });
+
+      if (this.openApiModel.paths[httpUrlEndpoint][httpMethodKey]!.responses === undefined) {
+        this.openApiModel.paths[httpUrlEndpoint][httpMethodKey]!.responses = {};
+      }
 
-    this.addReference(responseObjectResponse);
+      // Successful responses with a non-void return type always return a status code of 2000
+      this.openApiModel.paths[httpUrlEndpoint][httpMethodKey]!.responses!['200'] = {
+        description: methodMirror.docComment?.description ?? 'Status code 200',
+        content: {
+          'application/json': { schema: reference.schema },
+        },
+      };
+    };
   }
 
   private addReference(referenceHolder: { reference?: Reference }): void {

package/src/transpiler/openapi/parsers/ReferenceBuilder.ts

@@ -1,3 +1,4 @@
+import * as yaml from 'js-yaml';
 import {
   PropertiesObject,
   ReferenceObject,
@@ -6,8 +7,9 @@ import {
   SchemaObjectObject,
 } from '../../../model/openapi/open-api-types';
 import { TypeBundle, TypesRepository } from '../../../model/types-repository';
-import { ClassMirror, FieldMirror, PropertyMirror, Type } from '@cparra/apex-reflection';
+import { ClassMirror, DocCommentAnnotation, FieldMirror, PropertyMirror } from '@cparra/apex-reflection';
 import { ListObjectType, ReferencedType } from '@cparra/apex-reflection/index';
+import { ApexDocSchemaObject } from '../../../model/openapi/apex-doc-types';
 
 type TypeBundleWithIsCollection = TypeBundle & { isCollection: boolean };
 
@@ -64,12 +66,20 @@ export class ReferenceBuilder {
     const properties: PropertiesObject = {};
     let referencedComponents: ReferenceComponent[] = [];
     propertiesAndFields.forEach((current) => {
-      const pair = this.getReferenceType(current.typeReference);
-      properties[current.name] = pair.schema;
+      // Check for "@http-schema" annotations within properties themselves. If these are specified they
+      // take precedence over the property type itself.
+      const manuallyDefinedHttpSchema = current.docComment?.annotations.find(
+        (annotation) => annotation.name.toLowerCase() === 'http-schema',
+      );
+      if (manuallyDefinedHttpSchema) {
+        this.handleOverriddenSchema(manuallyDefinedHttpSchema, properties, current, referencedComponents);
+      } else {
+        const pair = this.getReferenceType(current.typeReference);
+        properties[current.name] = pair.schema;
+        pair.referenceComponents.forEach((current) => referencedComponents.push(current));
+      }
       properties[current.name].description = current.docComment?.description;
-      pair.referenceComponents.forEach((current) => referencedComponents.push(current));
     });
-
     const mainReferenceComponents = this.buildMainReferenceComponent(typeBundle, properties);
 
     // Make sure to add the "main" reference first
@@ -83,6 +93,28 @@ export class ReferenceBuilder {
     };
   }
 
+  private handleOverriddenSchema(
+    manuallyDefinedHttpSchema: DocCommentAnnotation,
+    properties: PropertiesObject,
+    current: FieldMirror | PropertyMirror,
+    referencedComponents: ReferenceComponent[],
+  ) {
+    // This can be of type ApexDocSchemaObject
+    const inYaml = manuallyDefinedHttpSchema?.bodyLines.reduce((prev, current, _) => prev + '\n' + current);
+    const asJson = yaml.load(inYaml) as ApexDocSchemaObject;
+    const isReference = this.isReferenceString(asJson);
+
+    if (isReference) {
+      const reference = this.build(asJson);
+      properties[current.name] = reference.entrypointReferenceObject;
+      reference.referenceComponents.forEach((current) => referencedComponents.push(current));
+    } else {
+      // If we are dealing with a manually defined schema object, we can add it directly to the "properties" map,
+      // because we don't need to add a reference component.
+      properties[current.name] = asJson;
+    }
+  }
+
   private getReferenceName(typeBundle: TypeBundleWithIsCollection): string {
     let referenceName = typeBundle.type.name;
     if (typeBundle.isChild) {
@@ -127,7 +159,7 @@ export class ReferenceBuilder {
     ];
   }
 
-  private getReferenceType(typeInMirror: ReferencedType): SchemaObjectReferencePair {
+  public getReferenceType(typeInMirror: ReferencedType): SchemaObjectReferencePair {
     // Returns a valid type supported by OpenApi from a received Apex type.
     const typeName = typeInMirror.type.toLowerCase();
     switch (typeName) {
@@ -180,6 +212,10 @@ export class ReferenceBuilder {
       referenceComponents: [...innerReference.referenceComponents],
     };
   }
+
+  private isReferenceString = (targetObject: any): targetObject is string => {
+    return typeof targetObject === 'string' || targetObject instanceof String;
+  };
 }
 
 type SchemaObjectReferencePair = {

package/src/transpiler/openapi/parsers/__tests__/ReferenceBuilder.spec.ts

@@ -3,6 +3,8 @@ import { ReferenceBuilder } from '../ReferenceBuilder';
 import { ClassMirrorBuilder } from '../../../../test-helpers/ClassMirrorBuilder';
 import { FieldMirrorBuilder } from '../../../../test-helpers/FieldMirrorBuilder';
 import { SchemaObjectArray, SchemaObjectObject } from '../../../../model/openapi/open-api-types';
+import { DocCommentBuilder } from '../../../../test-helpers/DocCommentBuilder';
+import { DocCommentAnnotationBuilder } from '../../../../test-helpers/DocCommentAnnotationBuilder';
 
 describe('ReferenceBuilder', () => {
   describe('Validation', () => {
@@ -619,4 +621,87 @@ describe('ReferenceBuilder', () => {
       expect((result.referenceComponents[1].schema as SchemaObjectObject).properties).toHaveProperty('fieldName');
     });
   });
+
+  describe('References can override their type', () => {
+    it("should correctly parse a manually defined schema in the reference's ApexDoc", function () {
+      const classMirror = new ClassMirrorBuilder()
+        .addFiled(
+          new FieldMirrorBuilder()
+            .withName('fieldName')
+            .withType('Object')
+            .withDocComment(
+              new DocCommentBuilder()
+                .addAnnotation(
+                  new DocCommentAnnotationBuilder().withName('http-schema').withBodyLines(['type: string']).build(),
+                )
+                .build(),
+            )
+            .build(),
+        )
+        .build();
+
+      TypesRepository.getInstance = jest.fn().mockReturnValue({
+        getFromAllByName: jest.fn().mockReturnValue({ type: classMirror, isChild: false }),
+      });
+
+      const result = new ReferenceBuilder().build('className');
+
+      const schema = result.referenceComponents[0].schema as SchemaObjectObject;
+      expect(schema.properties).toHaveProperty('fieldName');
+      const fieldSchema = schema.properties!['fieldName'] as SchemaObjectObject;
+      expect(fieldSchema.type).toBe('string');
+    });
+
+    it('should correctly parse a manually defined reference while parsing properties', function () {
+      const mainClassMirror = new ClassMirrorBuilder()
+        .withName('parent')
+        .addFiled(
+          new FieldMirrorBuilder()
+            .withName('childClassMember')
+            .withType('Object')
+            .withDocComment(
+              new DocCommentBuilder()
+                .addAnnotation(
+                  new DocCommentAnnotationBuilder().withName('http-schema').withBodyLines(['ChildClass']).build(),
+                )
+                .build(),
+            )
+            .build(),
+        )
+        .build();
+
+      const childClass = new ClassMirrorBuilder()
+        .withName('child')
+        .addFiled(
+          new FieldMirrorBuilder()
+            .withName('grandChildClassMember')
+            .withReferencedType({
+              type: 'GrandChildClass',
+              rawDeclaration: 'GrandChildClass',
+            })
+            .build(),
+        )
+        .build();
+
+      const grandChildClass = new ClassMirrorBuilder()
+        .withName('grandchild')
+        .addFiled(new FieldMirrorBuilder().withName('stringMember').withType('String').build())
+        .build();
+
+      TypesRepository.getInstance = jest.fn().mockReturnValue({
+        getFromAllByName: jest
+          .fn()
+          .mockReturnValueOnce({ type: mainClassMirror, isChild: false })
+          .mockReturnValueOnce({ type: childClass, isChild: false })
+          .mockReturnValueOnce({ type: grandChildClass, isChild: false }),
+      });
+
+      const result = new ReferenceBuilder().build('className');
+
+      expect(result.referenceComponents).toHaveLength(3);
+      expect(result.referenceComponents.some((ref) => ref.referencedClass === 'parent')).toBe(true);
+      expect(result.referenceComponents.some((ref) => ref.referencedClass === 'child')).toBe(true);
+      expect(result.referenceComponents.some((ref) => ref.referencedClass === 'grandchild')).toBe(true);
+    });
+  });
 });

package/docs/API/SampleClassWithoutModifier.md

@@ -1,11 +0,0 @@
-# SampleClassWithoutModifier
-
-`ISTEST`
-## Methods
-### `static thisIsAClassWithoutAModifier()`
-
-`ISTEST`
-
-This is a test method
-
----

package/docs/Main/GroupedClass.md

@@ -1,10 +0,0 @@
-# GroupedClass
-
-Uses a block style apex doc
-
-
-**Group** Main
-
-
-**Test Class** [SampleClass](/Main/SampleClass.md)
-

package/docs/Misc-Group/AnotherInterface.md

@@ -1 +0,0 @@
-# AnotherInterface

package/docs/Misc-Group/Reference2.md

@@ -1,7 +0,0 @@
-# Reference2
-## Fields
-
-### `stringMember` → `String`
-
-
----