Apex生成Swagger未展示SQL查询的函数与JSON对象数据问题

问题场景 #

你用Apex基于包含JSON_OBJECT、JSON_ARRAYAGG的复杂SQL生成REST API时，ORDS自动生成的Swagger文档无法识别嵌套JSON结构，要么把结果标记为CLOB类型，要么显示空的对象属性，完全体现不出实际返回的字段和嵌套层级。

可行解决方法 #

1. 手动补全Swagger Schema（最直接） #

找到Apex里对应REST模块的编辑入口，进入「响应」配置项，手动编写符合OpenAPI规范的Schema结构，完全对应你的SQL返回的JSON字段：

• 明确每个字段的类型（string、integer等）
• 定义嵌套数组和对象的层级
  示例Schema片段：

type: object
properties:
  institutionUuid:
    type: string
  name:
    type: string
  iKindCd:
    type: string
  branches:
    type: array
    items:
      type: object
      properties:
        branchUuid:
          type: string
        branchName:
          type: string
        branchCity:
          type: string

2. 用ORDS的JSON_SCHEMA函数提示结构 #

在你的SQL查询里加入JSON_SCHEMA字段，明确返回JSON的结构，ORDS会读取这个字段来生成正确的Swagger定义：

SELECT JSON_OBJECT(
  'institutionUuid' VALUE vw.uuid,
  'name' VALUE vw.name,
  'branches' VALUE branches
) AS institution,
-- 这里定义返回JSON的Schema
JSON_SCHEMA(
  '{"type":"object","properties":{"institutionUuid":{"type":"string"},"name":{"type":"string"},"branches":{"type":"array","items":{"type":"object","properties":{"branchUuid":{"type":"string"},"branchName":{"type":"string"},"branchCity":{"type":"string"}}}}}}'
) AS $schema
FROM (
  -- 你的原查询内容
  with branch as (...)
  select ...
)

3. 转成结构化视图再生成API #

把复杂的JSON查询转换成关系型视图，ORDS能更好识别视图的字段类型，之后再基于视图生成REST API：

• 先创建视图，把JSON_ARRAYAGG生成的分支字段作为视图的一个列
• 基于这个视图创建REST服务，ORDS会自动解析视图字段，生成包含正确结构的Swagger文档

4. 直接编辑生成的Swagger YAML #

如果已经导出了ORDS自动生成的Swagger文件，直接手动修改components/schemas部分，替换掉原有的CLOB或空结构，补充完整的字段和嵌套层级，再导入回Apex或者作为自定义文档使用。

内容的提问来源于stack exchange，提问作者noUserName97