@cparra/apexdocs 2.9.0 → 2.10.0

package/README.md

@@ -126,6 +126,8 @@ The CLI supports the following parameters:
 | --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       |
+| --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       |
 
 ### Importing to your project
 
@@ -374,17 +376,17 @@ or a fully defined custom schema (See the `Custom Schemas` section below).
 
 Example
 ```apex
-    /**
-     * @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() {
-      ///...
-    }
+/**
+ * @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,
@@ -400,25 +402,25 @@ whether it is `required` or not, a `description`, and a `schema`.
 
 Example
 ```apex
-    /**
-     * @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() {
-        // ..
-    }
+/**
+ * @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,
@@ -434,22 +436,22 @@ If no `description` is provided then one will be automatically built using the `
 📝 Note that you can specify as many `@http-parameter` annotations as needed.
 
 ```apex
-    /**
-     * @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() {
-        // ...
-    }
+/**
+ * @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
@@ -459,6 +461,49 @@ class will be parsed by the ApexDocs tool and automatically converted to a refer
 
 The tool will parse the class and create a reference that complies with [Apex's support for User-Defined Types](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_rest_methods.htm#ApexRESTUserDefinedTypes)
 
+##### 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
+
+```apex
+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).
+
+```apex
+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.
@@ -472,16 +517,16 @@ Maps are not supported, as it is not possible to know which keys the map will co
 to convert that to a valid specification. For this use case, define a Custom Schema as explained below.
 
 ```apex
-    /**
-     * @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() {
-      ///...
-    }
+/**
+ * @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,
@@ -489,16 +534,16 @@ by using the `ParentClassName.InnerClassName` syntax, even if the inner class re
 referencing it.
 
 ```apex
-    /**
-     * @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() {
-      ///...
-    }
+/**
+ * @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

package/docs/Main/nspc.GroupedClass.md

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

package/docs/Main/{SampleClass.md → nspc.SampleClass.md}

@@ -1,4 +1,4 @@
-# SampleClass
+# nspc.SampleClass
 
 `NAMESPACEACCESSIBLE`
 
@@ -6,9 +6,9 @@
 
 `STATUS: ACTIVE`
 
-This is a class description. This class relates to [SampleInterface](/Sample-Interfaces/SampleInterface.md)
+This is a class description. This class relates to [nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
              But this [ClassThatDoesNotExist](ClassThatDoesNotExist) does not exist.
-             You can also link using this syntax [SampleInterface](/Sample-Interfaces/SampleInterface.md)
+             You can also link using this syntax [nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
 
 
 **Group** Main
@@ -20,7 +20,7 @@ This is a class description. This class relates to [SampleInterface](/Sample-Int
 **Author** Cesar Parra
 
 
-**See** [SampleInterface](/Sample-Interfaces/SampleInterface.md)
+**See** [nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
 
 ## Constructors
 ### My Super Group
@@ -28,7 +28,7 @@ This is a class description. This class relates to [SampleInterface](/Sample-Int
 
 `NAMESPACEACCESSIBLE`
 
-Constructs a SampleClass without any arguments. This relates to [SampleInterface](/Sample-Interfaces/SampleInterface.md)
+Constructs a SampleClass without any arguments. This relates to [nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
 
 ###### Throws
 
@@ -40,7 +40,7 @@ Constructs a SampleClass without any arguments. This relates to [SampleInterface
 **CustomAnnotation** A Custom method annotation
 
 
-**See** [SampleInterface](/Sample-Interfaces/SampleInterface.md)
+**See** [nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
 
 ###### Example
 ```apex

package/docs/Misc-Group/nspc.AnotherInterface.md

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

package/docs/Misc-Group/{ChildClass.md → nspc.ChildClass.md}

@@ -1,17 +1,17 @@
-# ChildClass
+# nspc.ChildClass
 
 **Inheritance**
 
-[GrandparentClass](/Misc-Group/GrandparentClass.md)
+[nspc.GrandparentClass](/Misc-Group/nspc.GrandparentClass.md)
  > 
-[ParentClass](/Misc-Group/ParentClass.md)
+[nspc.ParentClass](/Misc-Group/nspc.ParentClass.md)
  > 
 ChildClass
 
 
 **Implemented types**
 
-[SampleInterface](/Sample-Interfaces/SampleInterface.md)
+[nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
 
 ## Fields
 

package/docs/Misc-Group/{GrandparentClass.md → nspc.GrandparentClass.md}

@@ -1,4 +1,4 @@
-# GrandparentClass
+# nspc.GrandparentClass
 ## Fields
 
 ### `protectedGrandParentField` → `String`

package/docs/Misc-Group/{InterfaceWithInheritance.md → nspc.InterfaceWithInheritance.md}

@@ -1,10 +1,10 @@
-# InterfaceWithInheritance
+# nspc.InterfaceWithInheritance
 
 **Extended types**
 
-[SampleInterface](/Sample-Interfaces/SampleInterface.md)
+[nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
 , 
-[AnotherInterface](/Misc-Group/AnotherInterface.md)
+[nspc.AnotherInterface](/Misc-Group/nspc.AnotherInterface.md)
 ## Methods
 ### `execute()`
 

package/docs/Misc-Group/{ParentClass.md → nspc.ParentClass.md}

@@ -1,8 +1,8 @@
-# ParentClass
+# nspc.ParentClass
 
 **Inheritance**
 
-[GrandparentClass](/Misc-Group/GrandparentClass.md)
+[nspc.GrandparentClass](/Misc-Group/nspc.GrandparentClass.md)
  > 
 ParentClass
 

package/docs/Misc-Group/{Reference1.md → nspc.Reference1.md}

@@ -1,4 +1,4 @@
-# Reference1
+# nspc.Reference1
 ## Fields
 
 ### `reference2Member` → `Reference2`

package/docs/Misc-Group/nspc.Reference2.md

@@ -0,0 +1,12 @@
+# nspc.Reference2
+## Fields
+
+### `objectReference` → `Object`
+
+
+This is an object reference.
+
+### `stringMember` → `String`
+
+
+---

package/docs/Misc-Group/{Reference3.md → nspc.Reference3.md}

@@ -1,4 +1,4 @@
-# Reference3
+# nspc.Reference3
 ## Fields
 
 ### `someBoolean` → `Boolean`

package/docs/Misc-Group/{Reference4.md → nspc.Reference4.md}

@@ -1,4 +1,4 @@
-# Reference4
+# nspc.Reference4
 ## Fields
 
 ### `someString` → `String`

package/docs/Misc-Group/{Reference5.md → nspc.Reference5.md}

@@ -1,4 +1,4 @@
-# Reference5
+# nspc.Reference5
 ## Fields
 
 ### `reference6Member` → `Reference6`

package/docs/Misc-Group/{Reference6.md → nspc.Reference6.md}

@@ -1,4 +1,4 @@
-# Reference6
+# nspc.Reference6
 ## Fields
 
 ### `grandChildString` → `String`

package/docs/Misc-Group/{SampleClassWithoutModifier.md → nspc.SampleClassWithoutModifier.md}

@@ -1,4 +1,4 @@
-# SampleClassWithoutModifier
+# nspc.SampleClassWithoutModifier
 
 `ISTEST`
 ## Methods

package/docs/Misc-Group/{SampleRestResource.md → nspc.SampleRestResource.md}

@@ -1,4 +1,4 @@
-# SampleRestResource
+# nspc.SampleRestResource
 
 `RESTRESOURCE`
 

package/docs/Misc-Group/{SampleRestResourceWithInnerClass.md → nspc.SampleRestResourceWithInnerClass.md}

@@ -1,4 +1,4 @@
-# SampleRestResourceWithInnerClass
+# nspc.SampleRestResourceWithInnerClass
 
 `RESTRESOURCE`
 

package/docs/README.md

@@ -1,71 +1,71 @@
 # Classes
 ## Misc Group
 
-### [AnotherInterface](/Misc-Group/AnotherInterface.md)
+### [nspc.AnotherInterface](/Misc-Group/nspc.AnotherInterface.md)
 
 
-### [ChildClass](/Misc-Group/ChildClass.md)
+### [nspc.ChildClass](/Misc-Group/nspc.ChildClass.md)
 
 
-### [GrandparentClass](/Misc-Group/GrandparentClass.md)
+### [nspc.GrandparentClass](/Misc-Group/nspc.GrandparentClass.md)
 
 
-### [InterfaceWithInheritance](/Misc-Group/InterfaceWithInheritance.md)
+### [nspc.InterfaceWithInheritance](/Misc-Group/nspc.InterfaceWithInheritance.md)
 
 
-### [ParentClass](/Misc-Group/ParentClass.md)
+### [nspc.ParentClass](/Misc-Group/nspc.ParentClass.md)
 
 
-### [Reference1](/Misc-Group/Reference1.md)
+### [nspc.Reference1](/Misc-Group/nspc.Reference1.md)
 
 
-### [Reference2](/Misc-Group/Reference2.md)
+### [nspc.Reference2](/Misc-Group/nspc.Reference2.md)
 
 
-### [Reference3](/Misc-Group/Reference3.md)
+### [nspc.Reference3](/Misc-Group/nspc.Reference3.md)
 
 
-### [Reference4](/Misc-Group/Reference4.md)
+### [nspc.Reference4](/Misc-Group/nspc.Reference4.md)
 
 
-### [Reference5](/Misc-Group/Reference5.md)
+### [nspc.Reference5](/Misc-Group/nspc.Reference5.md)
 
 
-### [Reference6](/Misc-Group/Reference6.md)
+### [nspc.Reference6](/Misc-Group/nspc.Reference6.md)
 
 
-### [SampleClassWithoutModifier](/Misc-Group/SampleClassWithoutModifier.md)
+### [nspc.SampleClassWithoutModifier](/Misc-Group/nspc.SampleClassWithoutModifier.md)
 
 
-### [SampleRestResource](/Misc-Group/SampleRestResource.md)
+### [nspc.SampleRestResource](/Misc-Group/nspc.SampleRestResource.md)
 
 Account related operations
 
 
 
-### [SampleRestResourceWithInnerClass](/Misc-Group/SampleRestResourceWithInnerClass.md)
+### [nspc.SampleRestResourceWithInnerClass](/Misc-Group/nspc.SampleRestResourceWithInnerClass.md)
 
 Contact related operations
 
 
 ## Main
 
-### [GroupedClass](/Main/GroupedClass.md)
+### [nspc.GroupedClass](/Main/nspc.GroupedClass.md)
 
 Uses a block style apex doc
 
 
 
-### [SampleClass](/Main/SampleClass.md)
+### [nspc.SampleClass](/Main/nspc.SampleClass.md)
 
-This is a class description. This class relates to [SampleInterface](/Sample-Interfaces/SampleInterface.md)
+This is a class description. This class relates to [nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
              But this [ClassThatDoesNotExist](ClassThatDoesNotExist) does not exist.
-             You can also link using this syntax [SampleInterface](/Sample-Interfaces/SampleInterface.md)
+             You can also link using this syntax [nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
 
 
 ## Sample Interfaces
 
-### [SampleInterface](/Sample-Interfaces/SampleInterface.md)
+### [nspc.SampleInterface](/Sample-Interfaces/nspc.SampleInterface.md)
 
 This is an interface description.
 

package/docs/Sample-Interfaces/{SampleInterface.md → nspc.SampleInterface.md}

@@ -1,4 +1,4 @@
-# SampleInterface
+# nspc.SampleInterface
 
 This is an interface description.
 

package/docs/index.html

@@ -1,22 +1,22 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Document</title>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-  <meta name="description" content="Description">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
-  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
-</head>
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: '',
-      repo: ''
-    }
-  </script>
-  <!-- Docsify v4 -->
-  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
-</body>
-</html>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: '',
+      repo: ''
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+</body>
+</html>

package/docs/{openapi.json → restapi.json}

@@ -1,12 +1,12 @@
 {
   "openapi": "3.1.0",
   "info": {
-    "title": "My REST Api 2",
+    "title": "Sample REST Api",
     "version": "1.0.0"
   },
   "servers": [
     {
-      "url": "/services/apexrest/"
+      "url": "/services/apexrest/nspc/"
     }
   ],
   "paths": {
@@ -253,17 +253,6 @@
       },
       "delete": {
         "description": "Sample HTTP Delete method with references to other types.",
-        "requestBody": {
-          "description": "This is an example of a request body",
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/SampleClass"
-              }
-            }
-          },
-          "required": true
-        },
         "parameters": [
           {
             "name": "limit",
@@ -419,9 +408,19 @@
         "properties": {
           "stringMember": {
             "type": "string"
+          },
+          "objectReference": {
+            "$ref": "#/components/schemas/Reference3_array",
+            "description": "This is an object reference."
           }
         }
       },
+      "Reference3_array": {
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/Reference3"
+        }
+      },
       "Reference3": {
         "type": "object",
         "properties": {

package/examples/force-app/main/default/restapi/SampleRestResource.cls

@@ -5,10 +5,6 @@
 global with sharing class SampleRestResource {
     /**
      * @description Sample HTTP Delete method with references to other types.
-     * @http-request-body
-     * description: This is an example of a request body
-     * required: true
-     * schema: SampleClass
      * @http-parameter
      * name: limit
      * in: header

package/examples/force-app/main/default/restapi/references/Reference2.cls

@@ -1,3 +1,9 @@
 public class Reference2 {
     public String stringMember;
+
+    /**
+     * @description This is an object reference.
+     * @http-schema List<Reference3>
+     */
+    public Object objectReference;
 }

package/lib/cli/generate.js

@@ -62,6 +62,16 @@ const argv = yargs.options({
         default: 'Apex REST Api',
         describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.',
     },
+    namespace: {
+        type: 'string',
+        describe: '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.",
+    },
+    openApiFileName: {
+        type: 'string',
+        describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
+        default: 'openapi',
+    },
 }).argv;
 settings_1.Settings.build({
     sourceDirectory: argv.sourceDir,
@@ -73,6 +83,8 @@ settings_1.Settings.build({
     defaultGroupName: argv.defaultGroupName,
     sanitizeHtml: argv.sanitizeHtml,
     openApiTitle: argv.openApiTitle,
+    namespace: argv.namespace,
+    openApiFileName: argv.openApiFileName,
 });
 Apexdocs_1.Apexdocs.generate();
 //# sourceMappingURL=generate.js.map