ApexSwag 🕶️

Giving your Apex REST endpoints the swagger they deserve.

ApexSwag is a Salesforce CLI plugin that transforms your @RestResource classes into beautiful, interactive OpenAPI 3.0 documentation — with a single command.

Created by Nishant Mohapatra

Prerequisites

Before installing ApexSwag, make sure you have the following:

1. Node.js (v18 or higher)

Download and install from nodejs.org

# Verify installation
node --version  # Should show v18.x.x or higher

2. Salesforce CLI

The Salesforce CLI (sf) is required. Install it using npm:

# Install Salesforce CLI globally
npm install -g @salesforce/cli

# Verify installation
sf --version

Or download from Salesforce CLI Setup Guide

3. Salesforce Org Access

You need access to a Salesforce org with Apex REST classes. This can be:

• A Developer Edition org (free at developer.salesforce.com)
• A Sandbox org
• A Scratch org

Installation

# Install ApexSwag plugin
sf plugins install apexswag

From Source (Development)

git clone https://github.com/nkmongit/apexswag.git
cd apexswag
npm install
npm run build
sf plugins link .

First-Time Setup

If this is your first time using ApexSwag, follow these steps:

Step 1: Authenticate Your Salesforce Org

# Open browser to log in to your Salesforce org
sf org login web

This opens your browser. Log in to your Salesforce org and authorize the CLI.

Step 2: Verify Connection

# List connected orgs
sf org list

You should see your org in the list.

Step 3: Run ApexSwag

# Generate documentation
sf apexswag generate

ApexSwag will scan your org for @RestResource classes and open the documentation UI.

Features

| Feature | Description | |---------|-------------| | 🚀 Auto Discovery | Scans your Salesforce Org for @RestResource classes | | 📖 ApexDoc Parsing | Extracts @description, @param, @return, and @tag annotations | | 🔐 Security Schemas | OAuth2 and Bearer authentication definitions | | ⚠️ Error Responses | Standard 400/401/403/404/500 response schemas | | 📝 Smart Examples | Auto-generated examples based on field names | | 🏷️ Tag Grouping | Group endpoints using @tag annotations | | 🔄 Dynamic Schemas | Fetch SObject field metadata including custom objects | | 💻 Interactive UI | Modern React-based documentation interface | | 📦 Postman Export | Export as Postman Collection v2.1 | | 💾 OpenAPI Export | Export JSON spec for CI/CD pipelines | | 👀 Watch Mode | Auto-reload when classes change |

Usage

Quick Start

# Interactive mode - select org and classes
sf apexswag generate

# Specify org and port
sf apexswag generate -o my-org -p 8080

# Export OpenAPI spec
sf apexswag generate --export -f api-spec.json

# Export Postman collection
sf apexswag generate --postman -f collection.json

# Watch mode
sf apexswag generate --watch

# Dynamic SObject schemas
sf apexswag generate --dynamic-sobjects

Command Flags

| Flag | Short | Description | Default | |------|-------|-------------|---------| | --target-org | -o | Target Salesforce Org | Interactive | | --port | -p | Server port | 3000 | | --export | -e | Export OpenAPI JSON | false | | --postman | | Export Postman Collection | false | | --output-file | -f | Output file path | openapi.json | | --class-names | -c | Comma-separated class names | All | | --watch | -w | Watch mode | false | | --dynamic-sobjects | | Fetch SObject schemas | false | | --no-security | | Exclude security definitions | false | | --no-errors | | Exclude error responses | false | | --no-examples | | Exclude example values | false |

ApexDoc Support

Annotations

/**
 * @description Creates a new Widget
 * @param name The widget name
 * @param count Number of items
 * @return The created Widget ID
 * @tag Widgets
 */
@HttpPost
global static String createWidget(String name, Integer count) { ... }

Inner Classes

global class RequestWrapper {
    public String name;
    public Integer age;
}

@HttpPost
global static void doPost(RequestWrapper req) { ... }

Generates schema with smart examples:

{ "name": "Acme Corporation", "age": 25 }

Troubleshooting

"No Salesforce orgs connected"

Run these commands:

sf org login web        # Authenticate an org
sf org list             # Verify it appears
sf apexswag generate    # Try again

"No @RestResource classes found"

Make sure your org has Apex classes with the @RestResource annotation:

@RestResource(urlMapping='/myEndpoint/*')
global class MyRestClass {
    @HttpGet
    global static String doGet() {
        return 'Hello World';
    }
}

Port already in use

Specify a different port:

sf apexswag generate -p 8080

Project Structure

apexswag/
├── src/
│   ├── commands/apexswag/    # CLI command
│   └── utils/                # Core utilities
│       ├── parser.ts         # Apex parsing
│       ├── openapi.ts        # OpenAPI generation
│       ├── server.ts         # Documentation server
│       └── sobjectService.ts # SObject schema fetching
├── ui/                       # React documentation UI
└── test/                     # Test suite

License

MIT © Nishant Mohapatra

Made with ❤️ for the Salesforce community