@cparra/apexdocs 2.8.2 → 2.9.0-alpha.1

package/src/model/openapi/open-api-types.ts

@@ -0,0 +1,112 @@
+// verified
+export type InfoObject = {
+  title: string;
+  version: string;
+};
+
+// verified
+export type ServerObject = {
+  url: string;
+};
+
+// verified
+export type PathsObject = {
+  [index: string]: PathItemObject;
+};
+
+// verified
+export type PathItemObject = {
+  description?: string;
+  get?: OperationObject;
+  put?: OperationObject;
+  post?: OperationObject;
+  delete?: OperationObject;
+  patch?: OperationObject;
+};
+
+// verified
+export type OperationObject = {
+  description?: string;
+  requestBody?: RequestBody;
+  parameters?: ParameterObject[];
+  responses?: ResponsesObject;
+};
+
+// Parameters
+export type ParameterObject = {
+  name: string;
+  in: 'query' | 'header' | 'path' | 'cookie';
+  description?: string;
+  required?: boolean;
+  schema?: SchemaObject;
+};
+
+// Request Body
+export type RequestBody = {
+  description?: string;
+  content: RequestBodyContent;
+  required?: boolean;
+};
+
+export type RequestBodyContent = {
+  [index: string]: MediaTypeObject; // Only key supported is "application/json" for now.
+};
+
+export type MediaTypeObject = {
+  schema?: SchemaObject;
+  example?: any; // TODO: Parse this on the output
+  examples?: { [index: string]: ExampleObject }; // TODO: Parse this on the output
+};
+
+export type ExampleObject = {
+  summary?: string;
+  description?: string;
+  value?: any;
+};
+
+// Responses
+export type ResponsesObject = {
+  [index: string]: ResponseObject; // The key will be the status code number
+};
+
+export type ResponseObject = {
+  description: string;
+  content?: ContentObject;
+};
+
+export type ContentObject = {
+  [index: string]: { schema: SchemaObject }; // key is usually 'application/json'
+};
+
+// Common
+export type SchemaObject = SchemaObjectObject | SchemaObjectArray | ReferenceObject;
+
+export type SchemaObjectObject = {
+  type: string; // This can be "object" (which would require properties), or a primitive
+  properties?: PropertiesObject;
+  format?: string;
+  description?: string;
+};
+
+export type PropertiesObject = {
+  [index: string]: SchemaObject;
+};
+
+export type SchemaObjectArray = {
+  type: 'array';
+  items: SchemaObject;
+  description?: string;
+};
+
+// Reference and components
+
+export type ReferenceObject = {
+  $ref: string;
+  description?: string;
+};
+
+export type ComponentsObject = {
+  schemas: {
+    [index: string]: SchemaObject;
+  };
+};

package/src/model/openapi/open-api.ts

@@ -0,0 +1,39 @@
+import { ComponentsObject, InfoObject, PathsObject, ServerObject } from './open-api-types';
+
+const OPEN_API_VERSION = '3.1.0';
+const SERVER_URL = '/services/apexrest/';
+
+/**
+ * Represents the OpenApi 3.1.0 spec
+ * https://spec.openapis.org/oas/v3.1.0
+ */
+export class OpenApi {
+  openapi = OPEN_API_VERSION;
+  info: InfoObject;
+  paths: PathsObject;
+  servers: ServerObject[];
+  components?: ComponentsObject;
+
+  constructor(title: string, version: string, public namespace?: string) {
+    this.info = {
+      title: title,
+      version: version,
+    };
+
+    this.servers = [
+      {
+        url: this.getServerUrl(),
+      },
+    ];
+
+    this.paths = {};
+  }
+
+  private getServerUrl(): string {
+    if (!this.namespace) {
+      return SERVER_URL;
+    }
+
+    return `${SERVER_URL}${this.namespace}/`;
+  }
+}

package/src/model/openapi/openapi-type-file.ts

@@ -0,0 +1,13 @@
+import { OutputFile } from '../outputFile';
+import { OpenApi } from './open-api';
+
+export class OpenapiTypeFile extends OutputFile {
+  constructor(public openApiModel: OpenApi) {
+    super('openapi', '');
+    this.addText(JSON.stringify(openApiModel, null, 2));
+  }
+
+  fileExtension(): string {
+    return '.json';
+  }
+}

package/src/model/{file.ts → outputFile.ts}

@@ -5,7 +5,7 @@ const xssFilter = new xss.FilterXSS({
   whiteList: { br: [], p: [], ul: [], li: [], code: [], pre: [] },
 });
 
-export abstract class File {
+export abstract class OutputFile {
   _contents = '';
 
   constructor(public fileName: string, public dir: string) {}

package/src/model/types-repository.ts

@@ -1,8 +1,11 @@
-import { Type } from '@cparra/apex-reflection';
+import { ClassMirror, Type } from '@cparra/apex-reflection';
+
+export type TypeBundle = { type: Type; isChild: boolean; parentType?: Type };
 
 export class TypesRepository {
   private static instance: TypesRepository;
-  private types: Type[] = [];
+  private scopedTypes: Type[] = [];
+  private allTypes: Type[] = [];
 
   public static getInstance(): TypesRepository {
     if (!TypesRepository.instance) {
@@ -11,11 +14,50 @@ export class TypesRepository {
     return TypesRepository.instance;
   }
 
-  public populate(types: Type[]) {
-    this.types = types;
+  public populateAll(types: Type[]) {
+    this.allTypes = types;
+  }
+
+  public getFromAllByName(typeName: string): TypeBundle | undefined {
+    if (typeName.includes('.')) {
+      // If it includes a dot we are assuming we are dealing with an inner class.
+      const [parentTypeName, childTypeName] = typeName.split('.');
+      const parentReference = this.allTypes.find(
+        (currentType: Type) => currentType.name.toLowerCase() === parentTypeName.toLowerCase(),
+      );
+      if (!parentReference || parentReference.type_name !== 'class') {
+        // If the parent is not found, no reason to keep searching, instead we return undefined.
+        // Similarly, if the parent is not a class, it means it cannot have children, so we return early.
+        return undefined;
+      }
+
+      const parentReferenceAsClass = parentReference as ClassMirror;
+      const childTypes = [
+        ...parentReferenceAsClass.classes,
+        ...parentReferenceAsClass.interfaces,
+        ...parentReferenceAsClass.enums,
+      ];
+      const foundType = childTypes.find((currentType: Type) => currentType.name.toLowerCase() === childTypeName);
+      if (!foundType) {
+        return undefined;
+      }
+      return { type: foundType, isChild: true, parentType: parentReference };
+    }
+
+    const foundType = this.allTypes.find(
+      (currentType: Type) => currentType.name.toLowerCase() === typeName.toLowerCase(),
+    );
+    if (!foundType) {
+      return undefined;
+    }
+    return { type: foundType, isChild: false };
+  }
+
+  public populateScoped(types: Type[]) {
+    this.scopedTypes = types;
   }
 
-  public getByName(typeName: string): Type | undefined {
-    return this.types.find((currentType: Type) => currentType.name === typeName);
+  public getFromScopedByName(typeName: string): Type | undefined {
+    return this.scopedTypes.find((currentType: Type) => currentType.name === typeName);
   }
 }

package/src/service/file-writer.ts

@@ -1,10 +1,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { File } from '../model/file';
+import { OutputFile } from '../model/outputFile';
 import { Settings } from '../settings';
 
 export class FileWriter {
-  static write(files: File[], onWriteCallback: (fileName: string) => void) {
+  static write(files: OutputFile[], onWriteCallback: (fileName: string) => void) {
     const outputDir = Settings.getInstance().outputDir;
     if (!fs.existsSync(outputDir)) {
       fs.mkdirSync(outputDir);

package/src/settings.ts

@@ -1,9 +1,4 @@
-import ProcessorTypeTranspiler from './transpiler/processor-type-transpiler';
-import { JekyllDocsProcessor } from './transpiler/markdown/jekyll/jekyll-docsProcessor';
-import DocsifyDocsProcessor from './transpiler/markdown/docsify/docsify-docs-processor';
-import { PlainMarkdownDocsProcessor } from './transpiler/markdown/plain-markdown/plain-docsProcessor';
-
-export type GeneratorChoices = 'jekyll' | 'docsify' | 'plain-markdown';
+import { GeneratorChoices } from './transpiler/generator-choices';
 
 export interface SettingsConfig {
   sourceDirectory: string;
@@ -14,6 +9,7 @@ export interface SettingsConfig {
   indexOnly: boolean;
   defaultGroupName: string;
   sanitizeHtml: boolean;
+  openApiTitle?: string;
 }
 
 export class Settings {
@@ -48,25 +44,8 @@ export class Settings {
     return this.config.outputDir;
   }
 
-  private static typeTranspilerCache?: ProcessorTypeTranspiler;
-
-  get typeTranspiler(): ProcessorTypeTranspiler {
-    if (Settings.typeTranspilerCache) {
-      return Settings.typeTranspilerCache;
-    }
-    switch (this.config.targetGenerator) {
-      case 'jekyll':
-        Settings.typeTranspilerCache = new JekyllDocsProcessor();
-        return Settings.typeTranspilerCache;
-      case 'docsify':
-        Settings.typeTranspilerCache = new DocsifyDocsProcessor();
-        return Settings.typeTranspilerCache;
-      case 'plain-markdown':
-        Settings.typeTranspilerCache = new PlainMarkdownDocsProcessor();
-        return Settings.typeTranspilerCache;
-      default:
-        throw Error('Invalid target generator');
-    }
+  get targetGenerator(): GeneratorChoices {
+    return this.config.targetGenerator;
   }
 
   get indexOnly(): boolean {
@@ -77,11 +56,11 @@ export class Settings {
     return this.config.sanitizeHtml;
   }
 
-  get numberOfVisibleDescriptionLinesOnHomePage() {
-    return 5;
-  }
-
   public getDefaultGroupName(): string {
     return this.config.defaultGroupName;
   }
+
+  public getOpenApiTitle(): string | undefined {
+    return this.config.openApiTitle;
+  }
 }

package/src/test-helpers/AnnotationBuilder.ts

@@ -0,0 +1,29 @@
+import { Annotation, AnnotationElementValue } from '@cparra/apex-reflection';
+
+/**
+ * Builder class to create Annotation objects.
+ * For testing purposes only.
+ */
+export class AnnotationBuilder {
+  private name = 'restresource';
+  private elementValues: AnnotationElementValue[] = [];
+
+  withName(name: string): AnnotationBuilder {
+    this.name = name;
+    return this;
+  }
+
+  addElementValue(elementValue: AnnotationElementValue): AnnotationBuilder {
+    this.elementValues.push(elementValue);
+    return this;
+  }
+
+  build(): Annotation {
+    return {
+      rawDeclaration: '',
+      name: this.name,
+      type: this.name,
+      elementValues: this.elementValues,
+    };
+  }
+}

package/src/test-helpers/ClassMirrorBuilder.ts

@@ -0,0 +1,56 @@
+import { Annotation, ClassMirror, DocComment, FieldMirror, MethodMirror } from '@cparra/apex-reflection';
+
+/**
+ * Builder class to create ClassMirror objects.
+ * For testing purposes only.
+ */
+export class ClassMirrorBuilder {
+  private name = 'SampleClass';
+  private annotations: Annotation[] = [];
+  private docComment?: DocComment;
+  private methods: MethodMirror[] = [];
+  private fields: FieldMirror[] = [];
+
+  withName(name: string): ClassMirrorBuilder {
+    this.name = name;
+    return this;
+  }
+
+  addAnnotation(annotation: Annotation): ClassMirrorBuilder {
+    this.annotations.push(annotation);
+    return this;
+  }
+
+  withDocComment(docComment: DocComment): ClassMirrorBuilder {
+    this.docComment = docComment;
+    return this;
+  }
+
+  addMethod(method: MethodMirror): ClassMirrorBuilder {
+    this.methods.push(method);
+    return this;
+  }
+
+  addFiled(field: FieldMirror): ClassMirrorBuilder {
+    this.fields.push(field);
+    return this;
+  }
+
+  build(): ClassMirror {
+    return {
+      annotations: this.annotations,
+      name: this.name,
+      type_name: 'class',
+      methods: this.methods,
+      implemented_interfaces: [],
+      properties: [],
+      fields: this.fields,
+      constructors: [],
+      enums: [],
+      interfaces: [],
+      classes: [],
+      access_modifier: 'public',
+      docComment: this.docComment,
+    };
+  }
+}

package/src/test-helpers/DocCommentAnnotationBuilder.ts

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

package/src/test-helpers/DocCommentBuilder.ts

@@ -0,0 +1,36 @@
+import { DocComment, DocCommentAnnotation } from '@cparra/apex-reflection';
+
+/**
+ * Builder class to create DocComment objects.
+ * For testing purposes only.
+ */
+export class DocCommentBuilder {
+  private description?: string;
+  private annotations: DocCommentAnnotation[] = [];
+
+  addAnnotation(annotation: DocCommentAnnotation): DocCommentBuilder {
+    this.annotations.push(annotation);
+    return this;
+  }
+
+  withDescription(description: string): DocCommentBuilder {
+    this.description = description;
+    return this;
+  }
+
+  build(): DocComment {
+    return {
+      paramAnnotations: [],
+      returnAnnotation: {
+        bodyLines: [],
+      },
+      exampleAnnotation: {
+        bodyLines: [],
+      },
+      throwsAnnotations: [],
+      annotations: this.annotations,
+      descriptionLines: [],
+      description: this.description ?? 'Sample Description',
+    };
+  }
+}

package/src/test-helpers/FieldMirrorBuilder.ts

@@ -0,0 +1,52 @@
+import { FieldMirror } from '@cparra/apex-reflection';
+import { ReferencedType } from '@cparra/apex-reflection/index';
+
+type MemberModifier = 'static' | 'webservice' | 'final' | 'override' | 'testmethod' | 'transient';
+
+export class FieldMirrorBuilder {
+  private accessModifier = 'public';
+  private name = 'fieldName';
+  private memberModifiers: MemberModifier[] = [];
+  private type: ReferencedType = {
+    type: 'String',
+    rawDeclaration: 'String',
+  };
+
+  withAccessModifier(accessModifier: string): FieldMirrorBuilder {
+    this.accessModifier = accessModifier;
+    return this;
+  }
+
+  withName(name: string): FieldMirrorBuilder {
+    this.name = name;
+    return this;
+  }
+
+  withType(type: string): FieldMirrorBuilder {
+    this.type = {
+      rawDeclaration: type,
+      type: type,
+    };
+    return this;
+  }
+
+  withReferencedType(type: ReferencedType): FieldMirrorBuilder {
+    this.type = type;
+    return this;
+  }
+
+  addMemberModifier(memberModifier: MemberModifier): FieldMirrorBuilder {
+    this.memberModifiers.push(memberModifier);
+    return this;
+  }
+
+  build(): FieldMirror {
+    return {
+      access_modifier: this.accessModifier,
+      annotations: [],
+      name: this.name,
+      memberModifiers: this.memberModifiers,
+      typeReference: this.type,
+    };
+  }
+}

package/src/test-helpers/MethodMirrorBuilder.ts

@@ -0,0 +1,37 @@
+import { Annotation, DocComment, MethodMirror } from '@cparra/apex-reflection';
+
+export class MethodMirrorBuilder {
+  private name = 'sampleMethod';
+  private annotations: Annotation[] = [];
+  private docComment?: DocComment;
+
+  withName(name: string): MethodMirrorBuilder {
+    this.name = name;
+    return this;
+  }
+
+  addAnnotation(annotation: Annotation): MethodMirrorBuilder {
+    this.annotations.push(annotation);
+    return this;
+  }
+
+  withDocComment(docComment: DocComment): MethodMirrorBuilder {
+    this.docComment = docComment;
+    return this;
+  }
+
+  build(): MethodMirror {
+    return {
+      access_modifier: 'public',
+      annotations: this.annotations,
+      name: this.name,
+      memberModifiers: [],
+      typeReference: {
+        type: 'void',
+        rawDeclaration: 'void',
+      },
+      parameters: [],
+      docComment: this.docComment,
+    };
+  }
+}

package/src/test-helpers/SettingsBuilder.ts

@@ -0,0 +1,21 @@
+import { SettingsConfig } from '../settings';
+
+/**
+ * Builder class to create SettingsConfig objects.
+ * For testing purposes only.
+ */
+export class SettingsBuilder {
+  build(): SettingsConfig {
+    return {
+      sourceDirectory: './',
+      recursive: true,
+      scope: [],
+      outputDir: './',
+      targetGenerator: 'openapi',
+      indexOnly: false,
+      defaultGroupName: 'Misc',
+      sanitizeHtml: true,
+      openApiTitle: 'Apex API',
+    };
+  }
+}

package/src/transpiler/factory.ts

@@ -0,0 +1,33 @@
+import ProcessorTypeTranspiler from './processor-type-transpiler';
+import { GeneratorChoices } from './generator-choices';
+import { JekyllDocsProcessor } from './markdown/jekyll/jekyll-docsProcessor';
+import DocsifyDocsProcessor from './markdown/docsify/docsify-docs-processor';
+import { PlainMarkdownDocsProcessor } from './markdown/plain-markdown/plain-docsProcessor';
+import { OpenApiDocsProcessor } from './openapi/open-api-docs-processor';
+
+export class TypeTranspilerFactory {
+  private static typeTranspilerCache?: ProcessorTypeTranspiler;
+
+  public static get(generator: GeneratorChoices): ProcessorTypeTranspiler {
+    if (this.typeTranspilerCache) {
+      return this.typeTranspilerCache;
+    }
+
+    switch (generator) {
+      case 'jekyll':
+        this.typeTranspilerCache = new JekyllDocsProcessor();
+        return this.typeTranspilerCache;
+      case 'docsify':
+        this.typeTranspilerCache = new DocsifyDocsProcessor();
+        return this.typeTranspilerCache;
+      case 'plain-markdown':
+        this.typeTranspilerCache = new PlainMarkdownDocsProcessor();
+        return this.typeTranspilerCache;
+      case 'openapi':
+        this.typeTranspilerCache = new OpenApiDocsProcessor();
+        return this.typeTranspilerCache;
+      default:
+        throw Error('Invalid target generator');
+    }
+  }
+}

package/src/transpiler/file-container.ts

@@ -1,13 +1,13 @@
-import { File } from '../model/file';
+import { OutputFile } from '../model/outputFile';
 
 export class FileContainer {
-  _files: File[] = [];
+  _files: OutputFile[] = [];
 
-  files(): File[] {
+  files(): OutputFile[] {
     return this._files;
   }
 
-  pushFile(file: File): void {
+  pushFile(file: OutputFile): void {
     this._files.push(file);
   }
 }

package/src/transpiler/generator-choices.ts

@@ -0,0 +1 @@
+export type GeneratorChoices = 'jekyll' | 'docsify' | 'plain-markdown' | 'openapi';

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

@@ -2,6 +2,7 @@ import { Type } from '@cparra/apex-reflection';
 import { TypesRepository } from '../../model/types-repository';
 import { Settings } from '../../settings';
 import State from '../../service/state';
+import { TypeTranspilerFactory } from '../factory';
 
 export default class ClassFileGeneratorHelper {
   public static getSanitizedGroup(classModel: Type) {
@@ -14,7 +15,7 @@ export default class ClassFileGeneratorHelper {
   }
 
   public static getFileLinkByTypeName(typeName: string) {
-    const type = TypesRepository.getInstance().getByName(typeName);
+    const type = TypesRepository.getInstance().getFromScopedByName(typeName);
     if (!type) {
       // If the type is not found we return a Markdown hyperlink with whatever we received.
       return `[${typeName}](${typeName})`;
@@ -25,7 +26,8 @@ export default class ClassFileGeneratorHelper {
 
   private static getDirectoryRoot(classModel: Type) {
     // root-relative links start from the root by using a leading '/'
-    if (Settings.getInstance().typeTranspiler.getLinkingStrategy() === 'root-relative') {
+    const generator = Settings.getInstance().targetGenerator;
+    if (TypeTranspilerFactory.get(generator).getLinkingStrategy() === 'root-relative') {
       return `/${this.getSanitizedGroup(classModel)}/`;
     }