@cparra/apexdocs 3.0.0 → 3.1.0

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

@@ -1,119 +0,0 @@
-// 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 = {
-  tags?: string[];
-  description?: string;
-  summary?: 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?: unknown;
-  examples?: { [index: string]: ExampleObject };
-};
-
-export type ExampleObject = {
-  summary?: string;
-  description?: string;
-  value?: unknown;
-};
-
-// 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;
-  };
-};
-
-export type TagObject = {
-  name: string;
-  description?: string;
-};

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

@@ -1,45 +0,0 @@
-import { ComponentsObject, InfoObject, PathsObject, ServerObject, TagObject } 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;
-  tags: TagObject[];
-  paths: PathsObject;
-  servers: ServerObject[];
-  components?: ComponentsObject;
-
-  constructor(
-    title: string,
-    version: string,
-    private namespace?: string,
-  ) {
-    this.info = {
-      title: title,
-      version: version,
-    };
-
-    this.servers = [
-      {
-        url: this.getServerUrl(),
-      },
-    ];
-
-    this.paths = {};
-    this.tags = [];
-  }
-
-  private getServerUrl(): string {
-    if (!this.namespace) {
-      return SERVER_URL;
-    }
-
-    return `${SERVER_URL}${this.namespace}/`;
-  }
-}

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

@@ -1,12 +0,0 @@
-import { OpenApi } from './open-api';
-import { OpenApiPageData } from '../shared/types';
-
-export function createOpenApiFile(fileName: string, openApiModel: OpenApi): OpenApiPageData {
-  const content = JSON.stringify({ ...openApiModel, namespace: undefined }, null, 2);
-  return {
-    outputDocPath: `${fileName}.json`,
-    content,
-    frontmatter: null,
-    group: null,
-  };
-}

package/src/core/openapi/parser.ts

@@ -1,163 +0,0 @@
-import { ClassMirror, InterfaceMirror, ReflectionResult, Type } from '@cparra/apex-reflection';
-import { Logger } from '#utils/logger';
-import { UnparsedSourceFile } from '../shared/types';
-
-export interface TypeParser {
-  parse(reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult): Type[];
-}
-
-type NameAware = { name: string };
-
-export class RawBodyParser implements TypeParser {
-  constructor(
-    private logger: Logger,
-    public typeBundles: UnparsedSourceFile[],
-  ) {}
-
-  parse(reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult): Type[] {
-    const types = this.typeBundles
-      .map((currentBundle) => {
-        this.logger.log(`Parsing file: ${currentBundle.filePath}`);
-        return reflect(currentBundle);
-      })
-      .filter((reflectionResult) => {
-        return reflectionResult.typeMirror;
-      })
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      .map((reflectionResult) => reflectionResult.typeMirror!);
-
-    return this.addFieldsFromParent(types);
-  }
-
-  addFieldsFromParent(types: Type[]): Type[] {
-    const typesWithFields: Type[] = [];
-    for (const currentType of types) {
-      if (currentType.type_name !== 'class' && currentType.type_name !== 'interface') {
-        typesWithFields.push(currentType);
-        continue;
-      }
-
-      if (currentType.type_name === 'class') {
-        let typeAsClass = currentType as ClassMirror;
-        if (!typeAsClass.extended_class) {
-          typesWithFields.push(currentType);
-          continue;
-        }
-
-        typeAsClass = this.addMembersFromParent(typeAsClass, types);
-        typesWithFields.push(typeAsClass);
-        continue;
-      }
-
-      // At this stage, we can be sure we are dealing with an interface
-      let typeAsInterface = currentType as InterfaceMirror;
-      if (!typeAsInterface.extended_interfaces.length) {
-        typesWithFields.push(currentType);
-        continue;
-      }
-
-      typeAsInterface = this.addMethodsFromParent(typeAsInterface, types);
-      typesWithFields.push(typeAsInterface);
-    }
-
-    return typesWithFields;
-  }
-
-  addMembersFromParent(currentClass: ClassMirror, allTypes: Type[]): ClassMirror {
-    if (!currentClass.extended_class) {
-      return currentClass;
-    }
-    const parent = allTypes.find((currentType: Type) => currentType.name === currentClass.extended_class);
-    if (!parent || parent.type_name !== 'class') {
-      return currentClass;
-    }
-
-    let parentAsClass = parent as ClassMirror;
-    if (parentAsClass.extended_class) {
-      parentAsClass = this.addMembersFromParent(parentAsClass, allTypes);
-    }
-
-    currentClass.fields = [...currentClass.fields, ...this.getInheritedFields(parentAsClass, currentClass)];
-    currentClass.properties = [...currentClass.properties, ...this.getInheritedProperties(parentAsClass, currentClass)];
-    currentClass.methods = [...currentClass.methods, ...this.getInheritedMethods(parentAsClass, currentClass)];
-    return currentClass;
-  }
-
-  addMethodsFromParent(currentInterface: InterfaceMirror, allTypes: Type[]): InterfaceMirror {
-    if (!currentInterface.extended_interfaces.length) {
-      return currentInterface;
-    }
-
-    const parents = [];
-    for (const currentInterfaceName of currentInterface.extended_interfaces) {
-      const parent = allTypes.find((currentType: Type) => currentType.name === currentInterfaceName);
-      if (parent) {
-        parents.push(parent);
-      }
-    }
-
-    for (const parent of parents) {
-      let parentAsInterface = parent as InterfaceMirror;
-      if (parentAsInterface.extended_interfaces.length) {
-        parentAsInterface = this.addMethodsFromParent(parentAsInterface, allTypes);
-      }
-
-      currentInterface.methods = [
-        ...currentInterface.methods,
-        ...this.getInheritedMethods(parentAsInterface, currentInterface),
-      ];
-    }
-
-    return currentInterface;
-  }
-
-  private getInheritedFields(parentAsClass: ClassMirror, currentClass: ClassMirror) {
-    return (
-      parentAsClass.fields
-        // Filter out private fields
-        .filter((currentField) => currentField.access_modifier.toLowerCase() !== 'private')
-        // Filter out fields that also exist on the child
-        .filter((currentField) => !this.memberExists(currentClass.fields, currentField.name))
-        .map((currentField) => ({
-          ...currentField,
-          inherited: true,
-        }))
-    );
-  }
-
-  private getInheritedProperties(parentAsClass: ClassMirror, currentClass: ClassMirror) {
-    return (
-      parentAsClass.properties
-        // Filter out private properties
-        .filter((currentProperty) => currentProperty.access_modifier.toLowerCase() !== 'private')
-        // Filter out properties that also exist on the child
-        .filter((currentProperty) => !this.memberExists(currentClass.properties, currentProperty.name))
-        .map((currentProperty) => ({
-          ...currentProperty,
-          inherited: true,
-        }))
-    );
-  }
-
-  private getInheritedMethods(
-    parentAsClass: ClassMirror | InterfaceMirror,
-    currentClass: ClassMirror | InterfaceMirror,
-  ) {
-    return (
-      parentAsClass.methods
-        // Filter out private methods
-        .filter((currentMethod) => currentMethod.access_modifier.toLowerCase() !== 'private')
-        // Filter out methods that also exist on the child
-        .filter((currentMethod) => !this.memberExists(currentClass.methods, currentMethod.name))
-        .map((currentMethod) => ({
-          ...currentMethod,
-          inherited: true,
-        }))
-    );
-  }
-
-  memberExists(members: NameAware[], fieldName: string): boolean {
-    const fieldNames = members.map((currentMember) => currentMember.name);
-    return fieldNames.includes(fieldName);
-  }
-}

package/src/core/openapi/parsers/Builder.ts

@@ -1,40 +0,0 @@
-import { Reference, ReferenceBuilder } from './ReferenceBuilder';
-import { ApexDocSchemaObject } from '../../../core/openapi/apex-doc-types';
-import { SchemaObject } from '../../../core/openapi/open-api-types';
-
-export type ApexDocSchemaAware = {
-  schema: ApexDocSchemaObject;
-};
-
-export abstract class Builder<T, K> {
-  build(schemaAware: ApexDocSchemaAware): Response<T> {
-    let reference: Reference | undefined;
-    if (this.isReferenceString(schemaAware.schema)) {
-      reference = new ReferenceBuilder().build(schemaAware.schema);
-    }
-
-    return {
-      reference: reference,
-      body: this.buildBody(schemaAware as K, reference),
-    };
-  }
-
-  abstract buildBody(apexDocObject: K, reference?: Reference): T;
-
-  protected getOpenApiSchemaFromApexDocSchema(schemaAware: ApexDocSchemaAware, reference?: Reference): SchemaObject {
-    if (this.isReferenceString(schemaAware.schema)) {
-      // We are dealing with a reference
-      return reference!.entrypointReferenceObject;
-    }
-    return schemaAware.schema;
-  }
-
-  private isReferenceString = (targetObject: unknown): targetObject is string => {
-    return typeof targetObject === 'string' || targetObject instanceof String;
-  };
-}
-
-export interface Response<T> {
-  reference?: Reference;
-  body: T;
-}

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

@@ -1,249 +0,0 @@
-import { ClassMirror, MethodMirror } from '@cparra/apex-reflection';
-import { OpenApi } from '../../../core/openapi/open-api';
-import * as yaml from 'js-yaml';
-import { ClassMirrorWrapper } from '../../../core/openapi/apex-type-wrappers/ClassMirrorWrapper';
-import { Reference, ReferenceBuilder } from './ReferenceBuilder';
-import { ParameterObjectBuilder } from './ParameterObjectBuilder';
-import { ResponsesBuilder } from './ResponsesBuilder';
-import {
-  ApexDocHttpRequestBody,
-  ApexDocHttpResponse,
-  ApexDocParameterObject,
-} from '../../../core/openapi/apex-doc-types';
-import { RequestBodyBuilder } from './RequestBodyBuilder';
-import { ApexDocSchemaAware } from './Builder';
-import { PropertiesObject, ReferenceObject } from '../../../core/openapi/open-api-types';
-import { MethodMirrorWrapper } from '../../../core/openapi/apex-type-wrappers/MethodMirrorWrapper';
-
-type FallbackMethodParser = (methodMirror: MethodMirror) => void;
-type AddToOpenApi<T extends ApexDocSchemaAware> = (input: T, urlValue: string, httpMethodKey: HttpOperations) => void;
-
-type HttpOperations = 'get' | 'put' | 'post' | 'delete' | 'patch';
-
-/**
- * Parses ApexDocs with HTTP REST annotations and turns them into an OpenApi specification.
- */
-export class MethodParser {
-  constructor(public openApiModel: OpenApi) {}
-
-  public parseMethod(classMirror: ClassMirror, httpUrlEndpoint: string, httpMethodKey: HttpOperations, tag: string) {
-    const classMirrorWrapper = new ClassMirrorWrapper(classMirror);
-    // Apex supports HttpGet, HttpPut, HttpPost, HttpDelete, and HttpPatch, so we search for a method
-    // that has one of those annotations.
-    const httpMethods = classMirrorWrapper.getMethodsByAnnotation(`http${httpMethodKey}`);
-    if (!httpMethods.length) {
-      return;
-    }
-
-    // We can assume there is at most one method per annotation, as this is an Apex rule.
-    const httpMethod = httpMethods[0];
-
-    this.openApiModel.paths[httpUrlEndpoint][httpMethodKey] = {};
-    this.openApiModel.paths[httpUrlEndpoint][httpMethodKey]!.tags = [tag];
-    if (httpMethod.docComment?.description) {
-      this.openApiModel.paths[httpUrlEndpoint][httpMethodKey]!.description = httpMethod.docComment.description;
-    }
-    const methodMirrorWrapper = new MethodMirrorWrapper(httpMethod);
-    if (methodMirrorWrapper.hasDocCommentAnnotation('summary')) {
-      this.openApiModel.paths[httpUrlEndpoint][httpMethodKey]!.summary =
-        methodMirrorWrapper.getDocCommentAnnotation('summary')?.body;
-    }
-
-    this.parseHttpAnnotation<ApexDocHttpRequestBody>(
-      httpMethod,
-      httpUrlEndpoint,
-      httpMethodKey,
-      'http-request-body',
-      this.addRequestBodyToOpenApi.bind(this),
-      this.fallbackHttpRequestBodyParser(httpUrlEndpoint, httpMethodKey),
-    );
-
-    this.parseHttpAnnotation<ApexDocParameterObject>(
-      httpMethod,
-      httpUrlEndpoint,
-      httpMethodKey,
-      'http-parameter',
-      this.addParametersToOpenApi.bind(this),
-    );
-
-    this.parseHttpAnnotation<ApexDocHttpResponse>(
-      httpMethod,
-      httpUrlEndpoint,
-      httpMethodKey,
-      'http-response',
-      this.addHttpResponsesToOpenApi.bind(this),
-      this.getFallbackHttpResponseParser(httpUrlEndpoint, httpMethodKey),
-    );
-  }
-
-  private parseHttpAnnotation<T extends ApexDocSchemaAware>(
-    httpMethod: MethodMirror,
-    urlValue: string,
-    httpMethodKey: HttpOperations,
-    annotationName: string,
-    addToOpenApi: AddToOpenApi<T>,
-    fallbackParser?: FallbackMethodParser,
-  ) {
-    const annotations = httpMethod.docComment?.annotations.filter((annotation) => annotation.name === annotationName);
-
-    if (!annotations?.length) {
-      if (fallbackParser) {
-        fallbackParser(httpMethod);
-      }
-      return;
-    }
-
-    for (const annotation of annotations) {
-      // We expect the ApexDoc data representing this to be in YAML format.
-      const inYaml = annotation?.bodyLines.reduce((prev, current) => prev + '\n' + current);
-
-      if (!inYaml) {
-        return;
-      }
-
-      this.addToOpenApiStrategy<T>(inYaml, urlValue, httpMethodKey, addToOpenApi);
-    }
-  }
-
-  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 T;
-    const requestBodyResponse = new RequestBodyBuilder().build(inJson);
-
-    addToOpenApi(inJson, urlValue, httpMethodKey);
-
-    this.addReference(requestBodyResponse);
-  }
-
-  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);
-  }
-
-  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![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 = {};
-      }
-
-      // 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 {
-    if (referenceHolder.reference) {
-      // If a reference is returned, we want to make sure to add it to the OpenApi object as well
-      // Add to "component" section if it hasn't been already
-      if (this.openApiModel.components === undefined) {
-        this.openApiModel.components = {
-          schemas: {},
-        };
-      }
-
-      if (!referenceHolder.reference.referenceComponents.length) {
-        return;
-      }
-
-      // Add all received references to the OpenApi components section.
-      referenceHolder.reference.referenceComponents.forEach((current) => {
-        // Check if the referenced object is already part of the OpenApi object
-        this.openApiModel.components!.schemas![current.referencedClass] = current.schema;
-      });
-    }
-  }
-}

package/src/core/openapi/parsers/ParameterObjectBuilder.ts

@@ -1,13 +0,0 @@
-import { ParameterObject } from '../../../core/openapi/open-api-types';
-import { Reference } from './ReferenceBuilder';
-import { ApexDocParameterObject } from '../../../core/openapi/apex-doc-types';
-import { Builder } from './Builder';
-
-export class ParameterObjectBuilder extends Builder<ParameterObject, ApexDocParameterObject> {
-  buildBody(apexDocObject: ApexDocParameterObject, reference?: Reference): ParameterObject {
-    return {
-      ...apexDocObject,
-      schema: this.getOpenApiSchemaFromApexDocSchema(apexDocObject, reference),
-    };
-  }
-}