课程章节介绍
嗨，同学，咱们接着看今天这一页内容。它讲的是什么呢？就是当我们为 Salesforce 里的 Apex REST 类生成了一份 OpenAPI 规范文档之后，一定要做的一件事：，仔细验证这份文档，确保它在“意思”上跟我们写的 REST 类完全一致，。
你别小看这一步，文档要是有偏差，后面不管是给别人调用、做测试，还是丢给 Agentforce 之类的平台去自动集成，都会出问题。所以咱们得像个质检员一样，把几个关键点一一核对清楚。
---
，首先，要确认几个大原则：，
- 这份规范必须是用 ，OpenAPI v3.0.0， 格式写的，这是目前最通用的标准。
- 服务器地址，也就是 `servers` 那一项，要设成 ，`/services/apexrest`，。因为 Salesforce 的 REST 服务都挂在这个路径下。
- 然后，所有 API 的访问路径，必须跟你 Apex 类上用 `@RestResource(urlMapping='...')` 定义的路由，一模一样，。路径前面不需要重复 `/services/apexrest`，因为服务器根路径已经配好了。
---
，接着，咱们要挨个检查这几个部分的语义是否匹配：，
1. ，路径参数，
比如你的 URL 是 `/Account/{Id}`，那 OpenAPI 里就要有对应的 `{Id}` 参数，而且类型要跟 Apex 方法的参数类型一致。不能多了，也不能少了。
2. ，HTTP 方法和请求路径，
Apex 里你用 `@HttpGet`、`@HttpPost` 等注解定义了方法，那 OpenAPI 里每个路径下的对应操作（get、post 等）就不能搞混。路径本身也要完全对上。
3. ，查询参数，
如果你的方法里通过 `RestContext.request.params` 获取参数，那么 OpenAPI 就要把这些参数列出来，写上名字、是否必填、类型是什么。尤其是那些不传就报错的，一定要标记成 `required`。
4. ，必填字段，
在请求体里，如果某个字段在 Apex 里做了非空校验，或者逻辑上必须传，那么在 OpenAPI 的 `requestBody` 的 schema 中，这个字段也要标成 `required`。
5. ，参数和字段的类型，
数字就是 `integer` 或 `number`，字符串是 `string`，布尔是 `boolean`，日期时间要对应到正确的 `format`，比如 `date-time`。别出现 Apex 里字段是数值，结果文档里写的是字符串类型，那调用方就可能传错数据。
6. ，请求体的形状，
OpenAPI 里 `requestBody` 描述的 JSON 结构，要跟 Apex 反序列化时用的那个类或 Map 的结构完全一致。包括嵌套对象、数组这些复杂形状，都得到一个字段一个字段地核实。
7. ，成功响应（2XX 状态码），
我们这里只重点验证 2 开头的成功响应就行了，因为课件里提到了范围 200–299。检查一下 OpenAPI 里定义的响应状态码是不是在这个范围内，不能把 200 写成了 201，或者漏掉了 204 这种无内容响应。
8. ，响应体的结构，
跟请求体类似，Apex 代码里 return 的对象序列化后是什么 JSON 形状，OpenAPI 的 `responses` 里就要原原本本地描述出来。最好用一个实际的返回样例去比对一下，一看结构就清楚了。
---
你把上面这些点都逐项核对过了，如果全部匹配，那这份 OpenAPI 文档在语义上就跟你的 Apex REST 类是相同的，值得信任。以后哪怕代码改了，也记得回来更新文档，再做一次这样的验证。这样，无论是团队协作、自动化测试，还是让 Agentforce 这样的智能体来调用你的接口，都不会因为文档不准确而掉坑里。
好，这一页的重点就是这些，咱们消化一下，有问题随时问。