Verify Metadata and OpenAPI Specification Documents

Use the sample files and table to confirm that the generated OpenAPI document is semantically identical to the REST class it was generated from.

  • Use the OpenAPI Specification Objects and Fields table to verify that all listed fields are valid.
  • Confirm whether the path needs a parameter defined /a/b/c/{id}. HttpGet and HttpDelete typically use an Id that is taken from the URI.
  • Confirm that the generated methods are listed under the correct path.
  • If the path defines a replaceable parameter, /a/b/c/{id}, confirm that the parameter is listed in the parameters section with the correct setting for the in property.
  • If the Apex REST class fetches values from query parameters, confirm that these parameters are listed in the parameters section with correct value in the in parameter.
  • Confirm that parameters that are required have the required parameter property set to true.
  • Confirm that all parameter types are correct.
  • If an Apex REST method depends on fetching values from the request body, confirm that the shape of the request body is correct.
  • Confirm that the generated YAML includes responses in the 200-299 range.
  • Confirm that the response body properly reflects the shape of the return type from the Apex REST class.

Sample of Generated Metadata XML and YAML 

CaseManager.yaml
1openapi: 3.0.0
2servers:
3 - url: /services/apexrest
4info:
5title: CaseManager
6 version: 1.0.0
7 description: This is an auto-generated OpenAPI v3 spec for CaseManager.
8paths:
9 /apex-rest-examples/v1/Cases/{caseId}:
10   description: Default description for the path.
11   get:
12     summary: Retrieve a case by its ID
13     description: Retrieve a case by its ID
14     operationId: getCaseById
15     parameters:
16       - name: caseId
17         in: path
18         required: true
19         description: The ID of the case to retrieve
20         schema:
21           type: string
22     responses:
23       "200":
24         description: Successful response
25         content:
26           application/json:
27             schema:
28               type: object
29               properties:
30                 CaseNumber:
31                   type: string
32                 Subject:
33                   type: string
34                 Status:
35                   type: string
36                 Origin:
37                   type: string
38                 Priority:
39                   type: string
40   delete:
41     summary: Delete a case
42     description: Deletes a case based on the provided case ID.
43     operationId: deleteCase
44     parameters:
45       - name: caseId
46         in: path
47         description: The ID of the case to delete
48         required: true
49         schema:
50           type: string
51     responses:
52       "204":
53         description: Case deleted successfully
54         content:
55           application/json:
56             schema:
57               type: object
58   patch:
59     summary: Update Case Fields
60     description: Update fields of a specific case identified by its ID.
61     operationId: updateCaseFields
62     parameters:
63       - name: caseId
64         in: path
65         description: The ID of the case to update
66         required: true
67         schema:
68           type: string
69     requestBody:
70       description: JSON object containing field names and their new values
71       required: true
72       content:
73         application/json:
74           schema:
75             type: object
76             properties:
77               subject:
78                 type: string
79               status:
80                 type: string
81               origin:
82                 type: string
83               priority:
84                 type: string
85     responses:
86       "200":
87         description: Successful update of the case
88         content:
89           application/json:
90             schema:
91               type: string
92 /apex-rest-examples/v1/Cases:
93   description: Default description for the path.
94   post:
95     summary: Create a new case
96     description: Creates a new case with the provided details.
97     operationId: createCase
98     requestBody:
99       description: Default description for the requestBody.
100       required: true
101       content:
102         application/json:
103           schema:
104             type: object
105             properties:
106               subject:
107                 type: string
108               status:
109                 type: string
110               origin:
111                 type: string
112               priority:
113                 type: string
114             required:
115               - subject
116               - status
117               - origin
118               - priority
119           description: Case creation details
120     responses:
121       "200":
122         description: Successfully created case
123         content:
124           application/json:
125             schema:
126               type: string
127   put:
128     summary: Upsert a case
129     description: Upsert a case based on the provided details.
130     operationId: upsertCase
131     requestBody:
132       description: Default description for the requestBody.
133       required: true
134       content:
135         application/json:
136           schema:
137             type: object
138             properties:
139               id:
140                 type: string
141               subject:
142                 type: string
143               status:
144                 type: string
145               origin:
146                 type: string
147               priority:
148                 type: string
149           description: Case details for upserting.
150     responses:
151       "200":
152         description: Successful operation
153         content:
154           application/json:
155             schema:
156               type: string
CaseManager.externalServiceRegistration-meta.xml
1<?xml version="1.0" encoding="UTF-8"?>
2<ExternalServiceRegistration xmlns="http://soap.sforce.com/2006/04/metadata">
3  <description>This is the ideal OpenAPI v3 specification for CaseManager.cls.</description>
4  <label>CaseManager</label>
5  <schemaType>OpenApi3</schemaType>
6  <schemaUploadFileExtension>yaml</schemaUploadFileExtension>
7  <schemaUploadFileName>casemanager_openapi</schemaUploadFileName>
8  <status>Complete</status>
9  <systemVersion>3</systemVersion>
10  <operations>
11    <name>getCaseById</name>
12    <active>true</active>
13  </operations>
14  <operations>
15    <name>createCase</name>
16    <active>true</active>
17  </operations>
18  <operations>
19    <name>deleteCase</name>
20    <active>true</active>
21  </operations>
22  <operations>
23    <name>upsertCase</name>
24    <active>true</active>
25  </operations>
26  <operations>
27    <name>updateCaseFields</name>
28    <active>true</active>
29  </operations>
30  <registrationProvider>CaseManager</registrationProvider>
31  <registrationProviderType>Custom</registrationProviderType>
32  <namedCredentialReference>null</namedCredentialReference>
33</ExternalServiceRegistration>

OpenAPI Specification Objects and Fields 

This table lists objects and fields in the OpenAPI specification that require specific values or actions to make the specification valid for use with Apex classes that you expose as agent actions. Make sure the OpenAPI specification you generate for these Apex classes is in agreement with the descriptions in this table.

FieldDescription
OpenAPI Object
openapiSet the OpenAPI Specification version 3.0.0.
serversSet the API server definition for the API to a single ‘/services/apexrest’ URL.
pathsSet the relative paths to the individual endpoints and their operations to exactly match the path defined in the @RestResource annotation’s urlMapping parameter.
securityApex REST supports these authentication mechanisms: - Type: OAuth2 - Type: HTTP, Scheme:Bearer
Path Item Object
descriptionProvide a detailed description of the path. Supports Markdown syntax.
serversDon’t include this field.
optionsDon’t include this field.
headDon’t include this field.
traceDon’t include this field.
Operations Object
descriptionProvide a detailed description of the operation. Supports Markdown syntax.
operationIdProvide a unique identifier for the operation. Useful for referencing the operation programmatically.
parametersProvide a list of unique parameter objects applicable for this operation, as needed. These parameters override matching parameters in the Path Item Object.
requestBodyProvide a request body describing the input data for this, if needed.
responsesProvide a responses object specifying the possible responses for the operation, if needed.
callbacksDon’t include this field.
deprecatedDon’t include this field.
securityDon’t include this field.
serversDon’t include this field.
Request Body Object
descriptionProvide a brief description of the request body. Can be used for documentation purposes.
contentUse only application/json for media type. This field is a map of media types and their corresponding schema for the request body.
Parameters Object
inProvide query, header, and path parameter locations. Don’t provide cookie.
descriptionProvide a brief description of the parameter’s purpose.
deprecatedDon’t include this field.
explodeDon’t include this field.
allowReservedDon’t include this field.
exampleThis field isn’t required, but we recommend that you include it.
examplesThis field isn’t required, but we recommend that you include it.
contentUse only application/json for media type. This field is a map of media types and their corresponding schema for the parameter.
Response Object
descriptionProvide a short description of the response. CommonMark syntax can be used for rich text representation.
headersDon’t include this field. Headers aren’t allowed in responses.
contentUse only application/json if the response has type: object, or text/plain if the response has type: string. This field is a map defining the response body.
Media Type Object
EncodingDon’t include this field.
Header ObjectDon’t use these headers: cookie, set-cookie, set-cookie2, content-length, Authorization. Don’t use allowed headers in response objects.
descriptionProvide a brief description of the header’s purpose.
deprecatedDon’t include this field.
explodeDon’t include this field.
allowReservedDon’t include this field.
exampleThis field isn’t required, but we recommend that you include it.
examplesThis field isn’t required, but we recommend that you include it.
contentUse only application/json for media type. This field is a map of media types and their corresponding schema for the header.
Callback ObjectDon’t use this object.
Schema ObjectInclude a properties object with the input properties that should be present. Don’t use not blocks.

Configure Extensions 

These boolean fields extend the OpenAPI specification. Use these fields to define agent actions that are automatically created and made available in agents. For MuleSoft for Agentforce: Topic Center extensions, see Configure Topics.

ExtensionDescription
x-sfdc/agent/action/publishAsAgentActionRequired. Set this attribute to true to enable the operation as an action.
x-sfdc/privacy/isPiiOptional. If publishAsAgentAction is enabled, set this attribute to true to enable PII service for queries sent under that operation
x-sfdc/agent/action/isUserInputRequired if publishAsAgentAction is enabled. Set this attribute to true to surface the field to the user for further input.
x-sfdc/agent/action/isDisplayableRequired if publishAsAgentAction is enabled. Set this attribute to true for the field to be displayable to the user.

The metadata must be defined inside a schema. For example:

1...
2components:
3  schemas:
4    Pet:
5      x-sfdc:
6        agent:
7            action:
8                isDisplayable: true
9...

Don’t add agent metadata in a schema that’s defined using $ref.

External Service Registration Metadata for Apex REST API Catalog 

ExternalServiceRegistration metadata deploys the OpenAPI document for your Apex REST class. The ExternalServiceRegistration fields are characteristic of an Apex REST service in the API catalog. The table below shows how these fields must be set:

Field NameField TypeDescription
namedCredentialstringThe field value is always null. The Apex REST service is deployed to your org.
registrationProviderstringThe name of the Apex REST class implementing the REST service.
registrationProviderTypeenum stringIndicates the type of the API specification registration. New enumeration value: ApexRest - The API spec is implemented by an Apex REST class in your org.
schemastringThe content of the OpenAPI 3.0 schema in YAML format. This field is empty if your SFDX project source behavior has been configured to decompose the ExternalServiceRegistration metadata.
schemaTypestringOpenApi3

ESR of provider type ApexRest aren’t visible in the External Service Setup. From Setup, in the Quick Find box, enter API Catalog and select it. See View Apex APIs in API Catalog.

Note

Deploying the ExternalServiceRegistration with registration provider type ApexRest doesn’t co-deploy the Apex REST class implementing the service automatically. You must deploy the Apex REST class as part of your project or on its own.

Note

Validate and Test API Documents 

In the MuleSoft for Agentforce Extension Pack, the MuleSoft for Agentforce API Design Extension provides the ability to check that your document is semantically and syntactically correct in Code Builder. The MuleSoft for Agentforce Extension Pack contains these extensions:

  • MuleSoft for Agentforce API Design Extension
  • MuleSoft for Agentforce Dependencies Extension
  • MuleSoft for Agentforce Platform Extension

Leverage Rulesets 

The Salesforce API Topic and Action Enablement and Salesforce Apex REST Best Practices governance rulesets are included in the MuleSoft for Agentforce Extension Pack. Use the governance rules in the extension pack to ensure that your document is ready for agent actions and has the required metadata to generate agent actions. Use these commands.

  • MuleSoft: Run Governance Validation with all Rulesets and Rules
  • MuleSoft: Rerun non-confirmation validations on Governance Rules runs rules that have previously failed.

For details, see Validating API Specifications Against Governance Rulesets and Enabling an API Project for Topics and Agent Actions.

Use API Console 

In the API Console, you can check endpoints and test your document by providing a deployed instance of your Apex REST implementation or by mocking up request data. For details, see Review Your Spec in the API Console and Test Your Spec Using the API Mocking Service.