@cparra/apexdocs 2.9.0 → 2.11.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
@@ -66,18 +66,18 @@ Constructs a SampleClass with an argument.
 ## Fields
 ### Common Constants
 
-* `ANOTHER_CONSTANT` → `String` (*Inherited*)  
-* `A_CONSTANT` → `String` (*Inherited*)  [`NAMESPACEACCESSIBLE` ]  - This is a constant.
-* `listOfStrings` → `List<String>` (*Inherited*)  
+* `ANOTHER_CONSTANT` → `String` 
+* `A_CONSTANT` → `String` [`NAMESPACEACCESSIBLE` ]  - This is a constant.
+* `listOfStrings` → `List<String>` 
 ---
 ### 'General' Constants
 
-* `GENERAL_ANOTHER_CONSTANT` → `String` (*Inherited*)  
-* `GENERAL_A_CONSTANT` → `String` (*Inherited*)  [`NAMESPACEACCESSIBLE` ]  - This is a constant.
+* `GENERAL_ANOTHER_CONSTANT` → `String` 
+* `GENERAL_A_CONSTANT` → `String` [`NAMESPACEACCESSIBLE` ]  - This is a constant.
 ---
 ### Other variables
 
-* `someVariable` → `String` (*Inherited*)  
+* `someVariable` → `String` 
 ---
 ## Properties
 
@@ -96,20 +96,21 @@ This is a String property.
 
 ---
 ## Methods
-### `static sampleMethod(String argument1, String argument2)`
+### A method group
+##### `static sampleMethod(String argument1, String argument2)`
 
 `NAMESPACEACCESSIBLE`
 
 Executes commands based on the passed in argument.
 
-#### Parameters
+###### Parameters
 
 |Param|Description|
 |---|---|
 |`argument1`|Argument1 to debug|
 |`argument2`|Argument2 to debug|
 
-#### Return
+###### Return
 
 **Type**
 
@@ -119,21 +120,23 @@ String
 
 Empty string
 
-#### Example
+###### Example
 ```apex
 String result = SampleClass.testMethod();
 System.debug(result);
 ```
 
 
-### `static anotherSampleMethod(String arg1)`
+##### `static anotherSampleMethod(String arg1)`
 
 Something here
 
 
 **Arg1** The arg1 description
 
-### `static call()`
+---
+### Other
+##### `static call()`
 
 Calls the method. This methods allows you to call it.
 

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/nspc.MemberGrouping.md

@@ -0,0 +1,13 @@
+# nspc.MemberGrouping
+## Fields
+### Group old syntax
+
+* `anotherInGroup1` → `String` 
+* `inGroup1` → `String` 
+---
+### Group new syntax
+Group's description
+
+* `anotherInGroup2` → `String` 
+* `inGroup2` → `String`  - Description for constant in group 2
+---

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`
 
@@ -12,9 +12,6 @@ Account related operations
 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 required: true description: My sample description. schema: SampleClass
 
 

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

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

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

@@ -0,0 +1,14 @@
+# nspc.SampleRestResourceWithoutApexDocs
+
+`RESTRESOURCE`
+
+Order related operations
+
+## Methods
+### `static doGet(String param1, Reference1 param2)`
+
+`HTTPGET`
+### `static doPatch(String param1, Reference1 param2)`
+
+`HTTPPATCH`
+---

package/docs/README.md

@@ -1,71 +1,80 @@
 # 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.MemberGrouping](/Misc-Group/nspc.MemberGrouping.md)
 
 
-### [Reference1](/Misc-Group/Reference1.md)
+### [nspc.ParentClass](/Misc-Group/nspc.ParentClass.md)
 
 
-### [Reference2](/Misc-Group/Reference2.md)
+### [nspc.Reference1](/Misc-Group/nspc.Reference1.md)
 
 
-### [Reference3](/Misc-Group/Reference3.md)
+### [nspc.Reference2](/Misc-Group/nspc.Reference2.md)
 
 
-### [Reference4](/Misc-Group/Reference4.md)
+### [nspc.Reference3](/Misc-Group/nspc.Reference3.md)
 
 
-### [Reference5](/Misc-Group/Reference5.md)
+### [nspc.Reference4](/Misc-Group/nspc.Reference4.md)
 
 
-### [Reference6](/Misc-Group/Reference6.md)
+### [nspc.Reference5](/Misc-Group/nspc.Reference5.md)
 
 
-### [SampleClassWithoutModifier](/Misc-Group/SampleClassWithoutModifier.md)
+### [nspc.Reference6](/Misc-Group/nspc.Reference6.md)
 
 
-### [SampleRestResource](/Misc-Group/SampleRestResource.md)
+### [nspc.SampleClassWithoutModifier](/Misc-Group/nspc.SampleClassWithoutModifier.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
 
 
+
+### [nspc.SampleRestResourceWithoutApexDocs](/Misc-Group/nspc.SampleRestResourceWithoutApexDocs.md)
+
+Order 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.