如何让ORDS生成准确展示复杂数据类型的OpenAPI 3.0文档？

安全阿岳

2026-7-16

解决ORDS生成OpenAPI文档无法识别嵌套自定义对象的问题

你遇到的问题是ORDS默认无法正确解析Oracle自定义嵌套对象的结构，导致OpenAPI文档中子对象被标记为String类型。以下是几个有效的解决办法：

1. 显式给REST服务指定响应Schema

ORDS支持通过函数注释里的@schema标签手动定义响应的结构，强制OpenAPI文档生成正确的嵌套类型。修改你的管道函数，添加ORDS的自定义注释：

CREATE OR REPLACE FUNCTION get_customers RETURN customer_tab PIPELINED
--ORDS:GET /customers
--ORDS:RESPONSE 200 @schema {
--  "type": "array",
--  "items": {
--    "type": "object",
--    "properties": {
--      "name": {"type": "string", "maxLength": 100},
--      "address": {
--        "type": "object",
--        "properties": {
--          "street": {"type": "string", "maxLength": 100},
--          "city": {"type": "string", "maxLength": 100},
--          "zip": {"type": "integer"}
--        }
--      }
--    }
--  }
--}
AS
BEGIN
  PIPE ROW(customer_obj('Example', address_obj('Street', 'City', 12345)));
  RETURN;
END;
/

部署这个函数后，ORDS生成的OpenAPI文档会按照你指定的Schema展示嵌套结构，不再把address标记为String。

2. 手动构造JSON返回，让ORDS自动推断Schema

如果不依赖Oracle自定义对象类型，直接用JSON_OBJECT和JSON_ARRAY构造返回结果，ORDS会自动解析JSON的层级结构，生成正确的OpenAPI Schema：

CREATE OR REPLACE FUNCTION get_customers RETURN CLOB
--ORDS:GET /customers
AS
BEGIN
  RETURN JSON_ARRAY(
    JSON_OBJECT(
      'name' VALUE 'Example',
      'address' VALUE JSON_OBJECT(
        'street' VALUE 'Street',
        'city' VALUE 'City',
        'zip' VALUE 12345
      )
    )
  );
END;
/

这种方式不需要手动写Schema，ORDS会根据返回的JSON样例自动识别嵌套对象的结构。