Generating an OpenAPI Spec for Salesforce REST API (Beta)

Salesforce now provides a beta feature that can generate an OpenAPI 3.0 specification for its sObjects REST API. This specification is generated directly from your org, so it reflects your current objects, fields, and configuration.

The output can be used with standard API tools for testing, SDK generation, and documentation, helping teams keep API definitions in sync with actual implementation.

Why It’s Useful

An up-to-date OpenAPI spec makes it easier to:

• Keep client integrations consistent with your current API structure.
• Standardize API documentation without manually creating JSON or YAML.
• Integrate Salesforce endpoints into automated testing and development workflows.

Practical Applications

Ways to use the generated spec include:

• Postman Collections — Import the spec to automatically create a test collection for your sObject API.
• SDK Generation — Use OpenAPI Generator to produce client libraries in multiple programming languages.
• Documentation Portals — Host the spec with tools like Redocly or Stoplight to provide interactive API documentation.

What’s Included in the Spec

The generated OpenAPI document can include these sObjects REST API endpoints:

• /sobjects – Lists all objects and metadata, including org encoding and query batch limits.
• /sobjects/{sObject} – Metadata for a single object; can also create records.
• /sobjects/{sObject}/describe – Detailed metadata for one object.
• /sobjects/{sObject}/{id} – Retrieve, update, or delete a record.
• /sobjects/{sObject}/updated – List records updated within a time range.
• /sobjects/{sObject}/deleted – List records deleted within a time range.
• /sobjects/{sObject}/{id}/{blobField} – Retrieve binary data from a blob field.
• /query – Run a SOQL query.
• /query/{queryLocator} – Retrieve the next batch of query results.

Step 1: Enable the Beta Feature

1. In Setup, search for User Interface.
2. Select Enable Salesforce Platform REST API, OpenAPI Spec Generation (Beta).
3. Save changes.

Requirements:

• Available in all editions, sandboxes, and scratch orgs (API Enabled).
• Permissions: Modify All Data or Customize Application.
• Must use the latest API version — currently v64.0 (Summer ’25).

Step 2: Start the Job

curl -X POST \
  https://YOUR_INSTANCE.my.salesforce.com/services/data/v64.0/async/specifications/oas3 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "resources": ["*"]
      }'

Selector Rules:

• "*" includes all supported resources; it can’t be combined with others.
• Paths like /sobjects/{sObject}/{id} must be written exactly with {}.
• No trailing slashes.
• To limit the spec to certain objects:

{
  "resources": [
    "/sobjects/{sObject}",
    "/sobjects/{sObject}/{id}"
  ],
  "sobjects": {
    "include": ["Account", "Contact"]
  }
}

Step 3: Check the Job Status

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://YOUR_INSTANCE.my.salesforce.com/services/data/v64.0/async/specifications/oas3/LOCATOR_ID

If "apiTaskStatus" is "INPROGRESS", wait and check again.

Step 4: Download and Convert

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://YOUR_INSTANCE.my.salesforce.com/services/data/v64.0/async/specifications/oas3/LOCATOR_ID/results \
  -o salesforce-openapi.json

Locator IDs expire after 48 hours.

Convert to YAML:

npx @redocly/cli bundle salesforce-openapi.json -o salesforce-openapi.yaml

Lint:

npx @redocly/cli lint salesforce-openapi.yaml

Build static docs:

npx @redocly/cli build-docs salesforce-openapi.yaml -o ./docs

Error Handling

• Unsupported or inaccessible resources are excluded from the spec.
• Failed requests return a 4xx or 5xx status.

Looking Ahead

This beta feature currently supports the sObjects REST API.
 If expanded to include other APIs like Composite, Bulk, or Tooling, it could further reduce the effort needed to set up and maintain integrations.