Readme images

README.md

@@ -9,10 +9,64 @@
 </div>
 
 ApexDocs is a non-opinionated documentation generator for Salesforce Apex classes.
-It can output documentation in Markdown
-format,
-which allows you to use the Static Site Generator of your choice to create a documentation site that fits your needs,
-hosted in any static web hosting service.
+It can output documentation in Markdown format, which allows you to use the Static Site Generator of your choice to
+create a documentation site that fits your needs, hosted in any static web hosting service.
+
+## 👀 Examples
+
+ApexDocs generates Markdown files, which can be integrated into any Static Site Generation (SSG) engine,
+(e.g. Jekyll, Vitepress, Hugo, Docosaurus, etc.) to create a documentation site that fits your needs.
+
+This gives you the flexibility to create beautiful leveraging your preferred SSG engine, which
+usually provides a wide range of themes, dark mode support, and other features out of the box.
+
+<div align="center">
+  <img src="imgs/vitepress-light.png" alt="Vitepress Light" width="45%" />
+  <img src="imgs/vitepress-dark.png" alt="Vitepress Dark" width="45%" />
+</div>
+
+*These are examples of documentation sites generated using Vitepress.
+Head over to the `examples/vitepress` folder to see the code.*
+
+The extra flexibility also lets you integrate the output documentation with your existing documentation site,
+allowing you to match the look and feel of your existing site.
+
+<div align="center">
+    <img src="imgs/integration.png" alt="Integration" width="70%" />
+</div>
+
+OpenApi REST definitions can be visualized using a tool like ReDoc, Swagger UI, or any other OpenApi viewer.
+
+<div align="center">
+    <img src="imgs/redocly.png" alt="OpenApi" width="70%" />
+</div>
+
+This repo contains several other example implementations in the `examples` directory, showcasing how to integrate
+with different tools.
+
+* [Examples](./examples)
+
+### In the wild
+
+Here are some live projects using ApexDocs:
+
+- [Trailhead Apex Recipes](https://github.com/trailheadapps/apex-recipes)
+- [Salesforce Commerce Apex Reference](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html)
+- [Expression (API)](https://cesarparra.github.io/expression/)
+- [Nimble AMS Docs](https://nimbleuser.github.io/nams-api-docs/#/api-reference/)
+
+## 🚀 Features
+
+* Generate documentation for Salesforce Apex classes as Markdown files
+* Generate an OpenApi REST specification based on `@RestResource` classes
+* Generate a changelog based on the differences between two versions of your Salesforce Apex classes
+* Support for grouping blocks of related code within a class
+* Support for ignoring files and members from being documented
+* Namespace support
+* Configuration file support
+* Single line ApexDoc Blocks
+* Custom tag support
+* And much, much more!
 
 ## 💿 Installation
 
@@ -49,38 +103,6 @@ Run the following command to generate a changelog for your Salesforce Apex class
 apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir force-app
 ```
 
-## 🚀 Features
-
-* Generate documentation for Salesforce Apex classes as Markdown files
-* Generate an OpenApi REST specification based on `@RestResource` classes
-* Generate a changelog based on the differences between two versions of your Salesforce Apex classes
-* Support for grouping blocks of related code within a class
-* Support for ignoring files and members from being documented
-* Namespace support
-* Configuration file support
-* Single line ApexDoc Blocks
-* Custom tag support
-* And much, much more!
-
-## 👀 Demo
-
-ApexDocs generates Markdown files, which can be integrated into any Static Site Generation engine,
-(e.g. Jekyll, Vitepress, Hugo, Docosaurus, etc.) to create a documentation site that fits your needs.
-
-This repo contains several example implementations in the `examples` directory, showcasing how to integrate
-with some of these tools.
-
-* [Examples](./examples)
-
-### In the wild
-
-Here are some live projects using ApexDocs:
-
-- [Trailhead Apex Recipes](https://github.com/trailheadapps/apex-recipes)
-- [Salesforce Commerce Apex Reference](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html)
-- [Expression (API)](https://cesarparra.github.io/expression/)
-- [Nimble AMS Docs](https://nimbleuser.github.io/nams-api-docs/#/api-reference/)
-
 ## ▶️ Available Commands
 
 ### Markdown

examples/open-api/docs/openapi.json

@@ -10,7 +10,7 @@
     }
   ],
   "paths": {
-    "AccountService/": {
+    "/AccountService/": {
       "description": "Account related operations",
       "get": {
         "tags": [
@@ -338,7 +338,7 @@
         }
       }
     },
-    "Contact/": {
+    "/Contact/": {
       "description": "Contact related operations",
       "get": {
         "tags": [
@@ -359,7 +359,7 @@
         }
       }
     },
-    "Order/": {
+    "/Order/": {
       "description": "Order related operations",
       "get": {
         "tags": [

examples/open-api/force-app/main/default/classes/dto/ChildClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/dto/Reference1.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/dto/Reference2.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/dto/Reference3.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/dto/Reference4.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/dto/Reference5.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/dto/Reference6.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/dto/Reference7.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/dto/SampleClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/rest/SampleRestResource.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/rest/SampleRestResourceToSkip.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/rest/SampleRestResourceWithInnerClass.cls

@@ -1,7 +1,7 @@
 /**
  * @description Contact related operations
  */
-@RestResource(urlMapping='/Contact/*')
+@RestResource(UrlMapping='/Contact/*')
 global with sharing class SampleRestResourceWithInnerClass {
     /**
      * @description This is a sample HTTP Get method

examples/open-api/force-app/main/default/classes/rest/SampleRestResourceWithInnerClass.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

examples/open-api/force-app/main/default/classes/rest/SampleRestResourceWithoutApexDocs.cls

@@ -1,7 +1,7 @@
 /**
  * @description Order related operations
  */
-@RestResource(urlMapping='/Order/*')
+@RestResource(UrlMapping='/Order/*')
 global with sharing class SampleRestResourceWithoutApexDocs {
     @HttpGet
     global static String doGet(String param1, Reference1 param2) {

examples/open-api/force-app/main/default/classes/rest/SampleRestResourceWithoutApexDocs.cls-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "3.3.1",
+  "version": "3.3.2",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",

src/core/openapi/__tests__/open-api-docs-processor.spec.ts

@@ -24,13 +24,13 @@ it('should add a path based on the @UrlResource annotation on the class', functi
   const processor = new OpenApiDocsProcessor(noLogger);
   processor.onProcess(classMirror);
 
-  expect(processor.openApiModel.paths).toHaveProperty('Account/');
+  expect(processor.openApiModel.paths).toHaveProperty('/Account/');
 });
 
 it('should respect slashes', function () {
   const annotationElementValue = {
     key: 'urlMapping',
-    value: "'v1/Account/*'",
+    value: "'/v1/Account/*'",
   };
   const classMirror = new ClassMirrorBuilder()
     .addAnnotation(new AnnotationBuilder().addElementValue(annotationElementValue).build())
@@ -39,7 +39,7 @@ it('should respect slashes', function () {
   const processor = new OpenApiDocsProcessor(noLogger);
   processor.onProcess(classMirror);
 
-  expect(processor.openApiModel.paths).toHaveProperty('v1/Account/');
+  expect(processor.openApiModel.paths).toHaveProperty('/v1/Account/');
 });
 
 it('should contain a path with a description when the class has an ApexDoc comment', function () {
@@ -55,5 +55,5 @@ it('should contain a path with a description when the class has an ApexDoc comme
   const processor = new OpenApiDocsProcessor(noLogger);
   processor.onProcess(classMirror);
 
-  expect(processor.openApiModel.paths['Account/'].description).toBe('My Description');
+  expect(processor.openApiModel.paths['/Account/'].description).toBe('My Description');
 });

src/core/openapi/open-api-docs-processor.ts

@@ -84,10 +84,10 @@ export class OpenApiDocsProcessor {
       return null;
     }
 
-    let endpointPath = urlMapping.value.replaceAll('"', '').replaceAll("'", '').replaceAll('/*', '/');
-    if (endpointPath.startsWith('/')) {
-      endpointPath = endpointPath.substring(1);
-    }
-    return endpointPath;
+    // The OpenApi path needs to start with a leading slash, but
+    // Salesforce @RestResource annotations already require a leading slash,
+    // so no need to check for it.
+    // See URL Guidelines: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_annotation_rest_resource.htm
+    return urlMapping.value.replaceAll('"', '').replaceAll("'", '').replaceAll('/*', '/');
   }
 }