Skip to content

cesarParra/apexdocs

Repository files navigation

ApexDocs

ApexDocs is a Node.js library with CLI capabilities to docGenerator documentation for Salesforce Apex classes.

License

Description

ApexDocs was originally built as an alternative to the Java based ApexDoc tool originally created by Aslam Bari and later maintained by Salesforce.org, as that tool is no longer being maintained.

ApexDocs is a Node.js library built on Typescript and hosted on npm. It offers CLI capabilities to automatically document your source code, based on the ApexDoc style of documentation. Additionally, it can be imported and consumed directly by your JavaScript code.

There are some key differences between ApexDocs and the Java based ApexDoc tool:

  • Recursive file search through your module directory structure. In an sfdx based project, all of your classes will be documented by specifying the top-most directory where file search should begin.
  • Unopinionated documentation site generation. Instead of creating HTML files, ApexDocs generates a Markdown (.md) file per Apex class being documented. This means you can host your files in static web hosting services that parse Markdown like Github Pages or Netlify, and use site generators like Jekyll or Gatsby. This gives you the freedom to decide how to style your site to match your needs.

Features

  • Custom Annotations

Any custom annotation defined in the Apexdoc is at the class level are supported, for example the following will be output to the resulting markdown file:

/**
 * @MyCustomAnnotation This is a custom annotation
 */
public class MyClass {
}
  • Single Line ApexDoc Blocks

πŸ“’ Note: If you wish to have multiple @ tags in a single line but don't want them to be treated as ApexDoc annotations, you can escape them by adding wrapping the annotation in ticks, for example

/**
 * @MyCustomAnnotation This is a custom annotation with an `@embedded` annotation
 */
  • Support for grouping blocks of related code within a class
  • Support for HTML tags
  • OpenApi REST specification generation
  • Support for ignoring files and members from being documented
  • Namespace support
  • Configuration file support
  • And much, much more!

Demo

ApexDocs currently supports generating markdown files for Jekyll and Docsify sites, as well as generating plain markdown files.

In the wild

Demo

Demo

Installation

npm i -g @cparra/apexdocs

Usage

CLI

apexdocs-generate
    -s src
    -t docs
    -p global
    -g docsify

The CLI supports the following parameters:

Parameter Alias Description Default Required
--sourceDir -s The directory location which contains your apex .cls classes. N/A Yes
--targetDir -t The directory location where documentation will be generated to. docs No
--recursive -r Whether .cls classes will be searched for recursively in the directory provided. true No
--scope -p A list of scopes to document. Values should be separated by a space, e.g --scope public private. Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource. global No
--targetGenerator -g Define the static file generator for which the documents will be created. Currently supports: jekyll, docsify, plain-markdown, and openapi. jekyll No
--indexOnly N/A Defines whether only the index file should be generated. false No
--defaultGroupName N/A Defines the @group name to be used when a file does not specify it. Miscellaneous No
--sanitizeHtml N/A When on, any special character within your ApexDocs is converted into its HTML code representation. This is specially useful when generic objects are described within the docs, e.g. "List< Foo>", "Map<Foo, Bar>" because otherwise the content within < and > would be treated as HTML tags and not shown in the output. Content in @example blocks are never sanitized. Apex REST Api No
--openApiTitle N/A If using "openapi" as the target generator, this allows you to specify the OpenApi title value. true No
--title N/A Allows you to specify the home page main title. If using "openapi" this acts as an alias to the openApiTitle parameter Classes No
--namespace N/A The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. If generating an OpenApi definition, it will be added to the file's Server Url. N/A No
--openApiFileName N/A If using "openapi" as the target generator, this allows you to specify the name of the output file. openapi No
--includeMetadata N/A Whether to include the file's meta.xml information: Whether it is active and and the API version false No
--documentationRootDir N/A The root directory where the documentation will be generated. This is useful when you want to generate the documentation in a subdirectory of your project. N/A No

Using a configuration file

You can also use a configuration file to define the parameters that will be used when generating the documentation. Apexdocs uses cosmiconfig to load the configuration file, which means it supports the following formats:

  • A package.json property, e.g. { "apexdocs": { "sourceDir": "src", "targetDir": "docs" } }
  • A .apexdocsrc file, written in YAML or JSON, with optional extensions: .yaml/.yml/.json/.js
  • An apexdocs.config.js file that exports an object
  • A apexdocs.config.ts file that exports an object

The configuration file should be placed in the root directory of your project.

Note that when using a configuration file, you can still override any of the parameters by passing them through the CLI.

When defining a .js or .ts configuration file, your object export can also contain the following functions that will allow you to override some of the default behavior:

  • onBeforeFileWrite - A function that will be called before a file is written to disk. It receives a TargetFile object that contains the file's content, path, and name, etc. It should return a TargetFile object with the updated content. The full object definition can be imported from @cparra/apexdocs/lib/settings
  • onAfterProcess - A function that will be called after all files have been processed. It receives a TargetFile[] array with all of the files that were processed and does not return anything.
import {TargetFile} from "@cparra/apexdocs/lib/settings";
export default {
  onBeforeFileWrite: (file: TargetFile): TargetFile => {
    console.log('onBefore writing', file);
    return file;
  },
  onAfterProcess: (files: TargetFile[]) => {
    console.log('onAfterProcess files', files);
  },
};

Importing to your project

If you are just interested in the Apex parsing capabilities, you can use the standalone Apex Reflection Library which is what gets used by this library behind the scenes to generate the documentation files.

Documentation Format

ApexDocs picks up blocks of comments throughout your .cls files. The block must begin with /** and end with */.

Documenting Classes

The following tags are supported on the class level:

Note Any custom generated tag is also supported. Custom tags can be added with at symbol (@) followed by the name of the tag. For example @custom-tag

Tag Description
@description One or more lines describing the class.
@see The name of a related class.
@group The group to which the class belongs to.
@author The author of the class. Note that this only gets added if it is explicitly defined through the configuration class that it should.
@date The date the class was created. Note that this only gets added if it is explicitly defined through the configuration class that it should.

Example

/**
 * @description This is my class description.
 */
public with sharing class TestClass {
}

Documenting Enums

The following tags are supported on the enum level:

Tag Description
@description One or more lines describing the enum.

Example

/**
 * @description This is my enum description.
 */
public Enum ExampleEnum {
    VALUE_1, VALUE_2
}

Documenting Properties

The following tags are supported on the property level:

Tag Description
@description One or more lines describing the property.

Example

/**
 * @description This is my property description.
 */
public String ExampleProperty { get; set; }

Documenting Methods and Constructors

Methods and constructors support the same tags.

The following tags are supported on the method level:

Tag Description
@description One or more lines describing the method.
@param paramName Description of a single parameter.
@return Description of the return value of the method.
@example Example of how the code can be used or called.
@throws ExceptionName Description of an exception thrown by the method.
@exception ExceptionName Same as @throws. V2 only

Example

/**
 * @description This is my method description.
 * @param action The action to execute.
 * @return The result of the operation.
 * @example
 * Object result = SampleClass.call('exampleAction');
 */
public static Object call(String action) {
}

Grouping Declarations Within A Class

A class might have members that should be grouped together. For example, you can have a class for constants with groups of constants that should be grouped together because they share a common behavior (e.g. different groups of constants representing the possible values for different picklists.)

You can group things together within a class by using the following syntax:

// @start-group Group Name or Description
public static final String CONSTANT_FOO = 'Foo';
public static final String CONSTANT_BAR = 'Bar';
// @end-group

Groups of members are displayed together under their own subsection after its name or description.

Some notes about grouping:

  • This is only supported on classes, NOT enums and interfaces
  • Supports
    • Properties
    • Fields (variables and constants)
    • Constructors
    • Methods
  • BUT only members of the same type are grouped together. For example, if you have a group that contains properties and methods the properties will be grouped together under Properties -> Group Name, and the methods will be grouped together under Methods -> Group Name
  • Does not support inner types (inner classes, interfaces, and enums)
  • It is necessary to use // @end-group whenever a group has been started, otherwise a parsing error will be raised for that file.

Inline linking

Apexdocs allows you to reference other classes from anywhere in your docs, and automatically creates a link to that class file for easy navigation.

Apexdocs recognizes 2 different syntax when linking files:

  • Javadoc's {@link FileName} syntax
  • A class name wrapped in between << >>.

Example

/**
 * @description This is my method description. This method receives an <<ExampleClass>>.
 * @param param1 An <<ExampleClass>> instance. Can also do {@link ExampleClass}
 * @return The result of the operation.
 */
public static Object doSomething(ExampleClass param1) {}

Email addresses can also be inlined linked by using the {@email EMAIL_ADDRESS} syntax.

HTML support

For the most part all HTML is sanitized when the --sanitizeHtml flag is passed a true value (which is the default). But there are some tags are allowed to have for the possibility of better styling long text.

  • Allowed tags are: br, p, ul, li, and code

Example

/**
 * @description <p>This is a paragraph</p>
 * <p>And this is another paragraph</p>
 * <ul>
 *     <li>This is a list item</li>
 *     <li>This is another list item</li>
 * </ul>
 */
class MyClass {
}

⚠️When the --sanitizeHtml flag is ON, any special character between code blocks (i.e. ```, `, or <code>) will also be escaped. So if you have references to Apex generic collections (Set, List, or Maps) they will not look right, as the < and > symbols will be escaped. To prevent this you can turn the flag off, but be aware of the special considerations when doing this described below.


For full control over the output you can also turn off the --sanitizeHtml flag, which will allow you to have any desired HTML within your docs.

⚠️When the --sanitizeHtml flag is OFF, references to Apex generic collections (Set, List or Maps) can be problematic as they will be treated as an HTML tag and not displayed. For example if you have something like @description Returns a List<String> the <String> portion will be treated as HTML and thus not appear on the page.

To fix this issue, when not sanitizing HTML, you should wrap any code that contain special characters that can be treated as HTML within '`' or within <code> tags.

Ignoring files and members

You can ignore files and members by using the @ignore tag on any ApexDoc block. If used at the class level, the entire file will be ignored. If used at the member level, only that member will be ignored.

Example

/**
 * @ignore
 */
public class MyClass {
    public static void myMethod() {}
}

Generating OpenApi REST Definitions

ApexDocs supports generating OpenApi 3.1.0 REST definitions based on any @RestResource classes in your source code.

Usage

To create an OpenApi specification file, run the apexdocs-generate and pass openapi to the --targetGenerator parameter. When using this generator, you can also pass a custom title through the --openApiTitle parameter. This title will be placed in the output file's info.title property, as defined by the OpenApi documentation for the Info Object

apexdocs-generate -s ./src -t docs -g openapi --openApiTitle "Custom OpenApi Title"

How It Works

When generating an OpenApi document, since @RestResource classes need to be global in Apex, the --scope parameter will be ignored. Instead, ApexDocs will run through all classes annotated with @RestResource and add it to the output OpenApi file.

Once it finishes running, a file named openapi.json will be created in the specified --targetDir.

Configuring What Gets Created

ApexDocs will automatically parse your source code and generate the OpenApi definition based on the HTTP related Apex annotations (RestResource, HttpDelete, HttpGet, HttpPatch, HttpPost, HttpGet). The different HTTP annotations will be used to generate a file that complies with the OpenApi Specification v3.1.0

Besides these annotations, the ApexDocs tool will also use any information provided through your code's Apexdocs, relying on some custom annotations that are specific to generating OpenApi definitions:

  • @http-request-body
  • @http-parameter
  • @http-response

@http-request-body

Allows you to specify the HTTP request's expected request body. It supports receiving a description, whether it is required or not, and a schema, which defines the shape of the object that is expected.

πŸ“ Note that only one @http-request-body should be defined per method. If you add more than one, only a single one will be used when generating the OpenApi definition.

The schema can either be a reference to another class in your source code (see the Class References section below) or a fully defined custom schema (See the Custom Schemas section below).

Example

/**
 * @description This is a sample HTTP Post method
 * @http-request-body
 * description: This is an example of a request body
 * required: true
 * schema: ClassName
 */ 
@HttpPost
global static void doPost() {
  ///...
}

πŸ“ Note that each parameter of this annotation is expected to be on its own line. Parameters are treated as YAML, so spacing is important.

@http-parameter

Allows you to specify any HTTP parameter expected by your method. It supports receiving a name, an in as defined by the supported Parameter Locations, whether it is required or not, a description, and a schema.

πŸ“ Note that you can specify as many @http-parameter annotations as needed.

Example

/**
 * @description This is a sample HTTP Post method
 * @return A String SObject.
 * @http-parameter
 * name: limit
 * in: query
 * required: true
 * description: Limits the number of items on a page
 * schema:
 *   type: integer
 * @http-parameter
 * name: complex
 * in: cookie
 * schema: MyClassName
 */
@HttpPost
global static String doPost() {
    // ..
}

πŸ“ Note that each parameter of this annotation is expected to be on its own line. Parameters are treated as YAML, so spacing is important.

@http-response

Allows you to specify any HTTP response returned by your method. It supports receiving a statusCode with the response code, a description, and a schema.

If no description is provided then one will be automatically built using the statusCode.

πŸ“ Note that you can specify as many @http-parameter annotations as needed.

/**
 * @description This is a sample HTTP Post method
 * @return A String SObject.
 * @http-response
 * statusCode: 200
 * schema: SuccessfulResponseClassName
 * @http-response
 * statusCode: 500
 * description: Status Code 500 - An internal server error occurred.
 * schema:
 *   type: string
 */
@HttpPost
global static String doPost() {
    // ...
}

Class References

Whenever specifying a schema parameter, you can pass as a string the name of any class in your source code. This class will be parsed by the ApexDocs tool and automatically converted to a reference in the resulting OpenApi definition.

The tool will parse the class and create a reference that complies with Apex's support for User-Defined Types

Reference Overrides

When dealing with references, there might be cases when you want to manually tell the parser what type of object a property or field is. For example, let's say we have a class that looks as follows

public class MyClass {
  public Object myObject;
  public Account myAccountRecord;
}

In this case myObject has a type of Object, and myAccountRecord is an SObject. Neither of these will be accurately parsed when building the OpenApi definition, instead they will be simple be referenced as object without any properties.

To accurately represent the shape of these objects, you can use the @http-schema annotation to essentially override its type during parsing. In this annotation you can specify the same thing you would in any schema property when dealing with any of the main @http-* methods, meaning a reference to another class, or a Custom Schema (as defined below).

public class MyClass {
  /**
   * @description This is a generic reference to another class 
   * @http-schema MyOtherClassName
   */
  public Object myObject;

  /**
   * @description This is a reference to an Account SObject
   * @http-schema
   * type: object
   * properties:
   *   Id:
   *     type: string
   *   Name:
   *     type: string
   *   CustomField__c:
   *     type: number
   */
  public Account myAccountRecord;
}

If dealing with a collection, you can also specify the name of the reference either using the List or Set syntax.

πŸ“ When using List or Set syntax in the schema of the ApexDoc @http-* annotation, only collections one level deep are supported (e.g. List<List> is not supported). This is only a limitation when referencing collections on the ApexDoc schema property directly, and is fully supported when multi-level collections are inside of a referenced class as part of your codebase.

Maps are not supported, as it is not possible to know which keys the map will contain, and thus it is not possible to convert that to a valid specification. For this use case, define a Custom Schema as explained below.

/**
 * @description This is a sample HTTP Post method
 * @http-request-body
 * description: This is an example of a request body
 * schema: List<ClassName>
 */
@HttpPost
global static void doPost() {
  ///...
}

Inner class references are also supported, but note that you need to pass the full name of the reference, by using the ParentClassName.InnerClassName syntax, even if the inner class resides on the same class as the HTTP method referencing it.

/**
 * @description This is a sample HTTP Post method
 * @http-request-body
 * description: This is an example of a request body
 * schema: ParentClass.InnerClass
 */
@HttpPost
global static void doPost() {
  ///...
}

Custom Schemas

For any schema parameter in any of the HTTP ApexDocs annotations, besides specifying the name of a class, you can also specify a custom schema definition. The schema definition can either be for a primitive type, an object or an array

Primitives

For primitives, you should specify the type and an optional format, as defined by the OpenApi Specification on Data Types

/**
 * ...
 * schema:
 *   type: string
 *   format: password
 */

Objects

To specify a custom object schema, use object as the type, and specify as many properties as follows:

/**
 * schema:
 *   type: object
 *   properties:
 *     id:
 *       type: string
 *       description: The super Id.
 *     name:
 *       type: string
 *     phone:
 *       type: string
 *       format: byte
*/

Properties can be defined as primitives (as explained above), other objects, or arrays (explained below)

Arrays

To specify a custom array schema, use array as the type, and provide an items definition. In items you can specify the definition of any other custom type (primitives, objects, or other arrays).

/**
 * schema:
 *   type: array
 *   items:
 *     type: object
 *     properties:
 *       name:
 *         type: string
 */

SObject References

ApexDocs is not able to automatically parse SObject references, as it can with class references, as it does not reach into your org to get existing SObject describes. Because of this, when dealing with SObject references you should create a Custom Schema as defined above. This will also allow you to specify which specific fields are being received or returned.

Considerations

Please be aware of the following when using ApexDocs to create an OpenApi definition:

  • Map references are resolved as object with no properties, as it is not possible to know which keys the map will contain. When using maps either create a class that better represents the shape of the object and use a Class Reference, or define a Custom Schema in the schema section of the ApexDoc itself.
  • Same thing when referencing SObjects, as SObject describe parsing is not supported by the ApexDocs tool. When referencing SObjects, consider defining a Custom Schema in the schema section of the ApexDoc.
  • ApexDoc is only able to parse through your source code, so references to other packages (namespaced classes) or any code that lives outside your source code is not supported. Consider creating a Custom Schema for those situations.
  • The return value and received parameters or your methods are currently not being considered when creating the OpenApi definition file. Instead, use the @http-response ApexDoc annotation to specify the return value, and @http-parameter to specify any expected parameter.

Typescript

ApexDocs provides all necessary type definitions.


1.X

Looking for documentation for version 1.X? Please refer to its branch