@cparra/apexdocs 2.9.0 → 2.10.0

package/src/settings.ts

@@ -10,6 +10,8 @@ export interface SettingsConfig {
   defaultGroupName: string;
   sanitizeHtml: boolean;
   openApiTitle?: string;
+  namespace?: string;
+  openApiFileName: string;
 }
 
 export class Settings {
@@ -63,4 +65,19 @@ export class Settings {
   public getOpenApiTitle(): string | undefined {
     return this.config.openApiTitle;
   }
+
+  public getNamespace(): string | undefined {
+    return this.config.namespace;
+  }
+
+  public getNamespacePrefix(): string {
+    if (!this.config.namespace) {
+      return '';
+    }
+    return `${this.config.namespace}.`;
+  }
+
+  public openApiFileName(): string {
+    return this.config.openApiFileName;
+  }
 }

package/src/test-helpers/DocCommentAnnotationBuilder.ts

@@ -2,17 +2,23 @@ import { DocCommentAnnotation } from '@cparra/apex-reflection';
 
 export class DocCommentAnnotationBuilder {
   private name = '';
+  private bodyLines: string[] = [];
 
   withName(name: string): DocCommentAnnotationBuilder {
     this.name = name;
     return this;
   }
 
+  withBodyLines(bodyLines: string[]): DocCommentAnnotationBuilder {
+    this.bodyLines = bodyLines;
+    return this;
+  }
+
   build(): DocCommentAnnotation {
     return {
       name: this.name,
       body: '',
-      bodyLines: [],
+      bodyLines: this.bodyLines,
     };
   }
 }

package/src/test-helpers/FieldMirrorBuilder.ts

@@ -1,9 +1,10 @@
-import { FieldMirror } from '@cparra/apex-reflection';
+import { DocComment, FieldMirror } from '@cparra/apex-reflection';
 import { ReferencedType } from '@cparra/apex-reflection/index';
 
 type MemberModifier = 'static' | 'webservice' | 'final' | 'override' | 'testmethod' | 'transient';
 
 export class FieldMirrorBuilder {
+  private docComment: DocComment | undefined = undefined;
   private accessModifier = 'public';
   private name = 'fieldName';
   private memberModifiers: MemberModifier[] = [];
@@ -40,6 +41,11 @@ export class FieldMirrorBuilder {
     return this;
   }
 
+  withDocComment(docComment: DocComment): FieldMirrorBuilder {
+    this.docComment = docComment;
+    return this;
+  }
+
   build(): FieldMirror {
     return {
       access_modifier: this.accessModifier,
@@ -47,6 +53,7 @@ export class FieldMirrorBuilder {
       name: this.name,
       memberModifiers: this.memberModifiers,
       typeReference: this.type,
+      docComment: this.docComment,
     };
   }
 }

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/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) {
@@ -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`
-
-
----