Generate OpenAPI and Metadata Documents and Configure an Agent Action

Follow these steps to create your first OpenAPI document. Use the sample Apex REST class and the generated files that we’re providing to quickly learn about the workflow. If you prefer, you can use one of the Apex REST classes you retrieved.

Generate the Files

In VS Code or Agentforce Vibes IDE, open the Command Palette (⇧⌘P) and run the command SFDX: Create Project command to create a new Salesforce project.
Run SFDX: Set a Default Org to select the org to which you want to deploy the new OAS.
If you aren’t using a class you retrieved, run SFDX: Create Apex Class to create a new Apex class. For example, create a class called CaseManager.
Write your Apex class using Apex REST annotations. For example, you can copy this code and paste it into the CaseManager.cls file that you just created.

1@RestResource(urlMapping='/apex-rest-examples/v1/Cases/*')
2global with sharing class CaseManager {
3    @HttpGet
4    global static Case getCaseById() {
5        RestRequest request = RestContext.request;
6        // grab the caseId from the end of the URL
7        String caseId = request.requestURI.substring(
8          request.requestURI.lastIndexOf('/')+1);
9        Case result =  [SELECT CaseNumber,Subject,Status,Origin,Priority
10                        FROM Case
11                        WHERE Id = :caseId];
12        return result;
13    }
14
15    @HttpPost
16    global static ID createCase(String subject, String status,
17        String origin, String priority) {
18        Case thisCase = new Case(
19            Subject=subject,
20            Status=status,
21            Origin=origin,
22            Priority=priority);
23        insert thisCase;
24        return thisCase.Id;
25    }
26
27    @HttpDelete
28    global static void deleteCase() {
29        RestRequest request = RestContext.request;
30        String caseId = request.requestURI.substring(
31            request.requestURI.lastIndexOf('/')+1);
32        Case thisCase = [SELECT Id FROM Case WHERE Id = :caseId];
33        delete thisCase;
34    }
35
36    @HttpPut
37    global static ID upsertCase(String subject, String status,
38        String origin, String priority, String id) {
39        Case thisCase = new Case(
40                Id=id,
41                Subject=subject,
42                Status=status,
43                Origin=origin,
44                Priority=priority);
45        // Match case by Id, if present.
46        // Otherwise, create new case.
47        upsert thisCase;
48        // Return the case ID.
49        return thisCase.Id;
50    }
51
52    @HttpPatch
53    global static ID updateCaseFields() {
54        RestRequest request = RestContext.request;
55        String caseId = request.requestURI.substring(
56            request.requestURI.lastIndexOf('/')+1);
57        Case thisCase = [SELECT Id FROM Case WHERE Id = :caseId];
58        // Deserialize the JSON string into name-value pairs
59        Map<String, Object> params = (Map<String, Object>)JSON.deserializeUntyped(request.requestbody.tostring());
60        // Iterate through each parameter field and value
61        for(String fieldName : params.keySet()) {
62            // Set the field and value on the Case sObject
63            thisCase.put(fieldName, params.get(fieldName));
64        }
65        update thisCase;
66        return thisCase.Id;
67    }
68}

Run SFDX: Refresh SObjects Definitions to bring org metadata in the form of object definitions into your project. Select All SObjects.
Run SFDX: Create OpenAPI Document from this Class from the command palette or the context menu.
Enter the folder where you want to store the generated files or accept the default externalServiceRegistration folder.
The command generates the files <ApexClass>.yaml, and <ApexClass>.externalServiceRegistration-meta.xml.
The description that appears in your org’s API catalog comes from the top-level description mapping in the YAML file, not the <description> element of the XML file.
Note
To verify the validity of the generated YAML and XML files, see Verify Metadata and OpenAPI Documents. Also, check the Problems in the Panel bar for error messages and warnings and fix the generated files as needed.
Run SFDX: Validate OpenAPI Document on the corrected YAML file to ensure all the errors and warnings are gone.
If the MuleSoft for Agentforce Extension Pack is installed, then SFDX: Validate OpenAPI Document isn’t available. Use the governance rules in the MuleSoft for Agentforce Extension Pack to validate your OpenAPI document. For details, see Verify Metadata and OpenAPI Specification Documents.
Note
Run the SFDX: Deploy This Source to Org command to deploy the CaseManager.cls class , or the class you’re working with, to your org.
Next deploy the generated XML file to the org. Note that the command to deploy isn’t ‌available on the YAML file.

Regenerate OpenAPI Documents

You can regenerate an OpenAPI document if you modify the Apex class associated with it:

Make the changes to the Apex class associated with the OpenAPI document.
Run the SFDX: Create OpenAPI Document from this Class command.
Select Overwrite or Manually merge with existing ESR the popup window. Overwrite directly overwrite the existing OpenAPI document (This action is irreversible). The Manually Merge with Existing ESR option opens a diff window comparing the original and new OpenAPI documents. The new files are generated with the naming format: <ApexClass>_<timestamp>.externalServiceRegistration-meta.xml and <ApexClass>_<timestamp>.yaml.These files are located in the esr_files_for_merge folder in the root directory of your Salesforce project.
Check the Problems tab for any errors or warnings in the new OpenAPI document (identified by the timestamp) and manually merge the changes from the newly generated OpenAPI document into the original document.
Run the SFDX: Validate OpenAPI Document command on the merged or overwritten OpenAPI document.
Deploy the validated OpenAPI document to your Salesforce org.

You may encounter API Catalog limits when deploying. See Limits.

Note

Confirm the Availability of the Agent Action

Once deployed, your API and its operations are available in your org’s API catalog.

From Setup, in the Quick Find box, enter API Catalog and select it. See View Apex APIs in API Catalog.
Click the Apex tab. The deployed API is listed.
The API and its operations are now available as an Apex Reference Action type that can be used to Create a Custom Agent Action.