OpenAPI 参考

数据墙DBW 自动为所有启用了 REST 的实体生成 OpenAPI 3.0.1 规范文档，并提供 Swagger UI 进行交互式 API 浏览。生成的规范是权限感知的——只显示当前角色有权访问的操作和字段。

OpenAPI 描述文档

引擎使用运行时配置和每个启用 REST 的实体的数据库元数据生成 OpenAPI 描述文档。规范使用 OpenAPI.NET SDK 构建，符合 OpenAPI 规范 v3.0.1，输出为 JSON 文档。

端点

GET /{rest-path}/openapi

默认 rest-path 为 api，完整路径为 /api/openapi。

权限感知的 OpenAPI

OpenAPI 文档反映每个实体配置的实际权限。生成的规范仅显示给定角色可访问的 HTTP 方法和字段。

权限到 HTTP 方法的映射

配置的权限操作	OpenAPI 中出现的 HTTP 方法
read	GET
create	POST
create + update	PUT、PATCH
delete	DELETE

如果 anonymous 角色对 Book 实体只有 read 权限，该角色看到的 OpenAPI 文档只包含 GET /api/Book。POST、PUT、PATCH、DELETE 被完全省略。

字段级过滤

当权限包含 fields.include 或 fields.exclude 时，OpenAPI 架构的请求和响应 schema 中仅出现该角色可访问的字段。被排除的字段不出现在 OpenAPI 文档中。

角色特定的 OpenAPI 路径

数据墙DBW 提供按角色的 OpenAPI 端点，可查看任意已配置角色的 API 文档：

GET /{rest-path}/openapi
GET /{rest-path}/openapi/anonymous
GET /{rest-path}/openapi/authenticated
GET /{rest-path}/openapi/<custom-role>

路径	行为
/openapi	返回默认视图（等同于 /openapi/anonymous）
/openapi/anonymous	过滤为 anonymous 角色可见的操作和字段
/openapi/authenticated	过滤为 authenticated 角色可见的操作和字段
/openapi/{custom-role}	过滤为命名角色的操作和字段

IMPORTANT

角色特定的 OpenAPI 路径（/openapi/{role}）仅在开发模式下可用。生产模式下这些端点被禁用以防止角色枚举。生产模式下只有基础 /openapi 路径可用。

NOTE

如果角色在运行时配置的任何实体上都没有 permissions 条目，该角色的特定端点返回 404 Not Found。只有至少在一个实体上配置了权限的角色才会生成 OpenAPI 文档。

权限感知示例

{
  "Book": {
    "permissions": [
      {
        "role": "anonymous",
        "actions": [
          {
            "action": "read",
            "fields": { "include": ["id", "title", "year"] }
          }
        ]
      },
      {
        "role": "authenticated",
        "actions": ["create", "read", "update", "delete"]
      }
    ]
  }
}

用此配置：

• /api/openapi/anonymous：仅显示 GET /api/Book，响应字段为 id、title、year。
• /api/openapi/authenticated：显示 GET、POST、PUT、PATCH、DELETE 全部操作，包含所有字段。

Swagger UI

Swagger UI 提供基于 OpenAPI 规范的交互式 Web API 浏览界面。

端点

GET /swagger

NOTE

Swagger UI 的路径 /swagger 不嵌套在 rest-path 下，以避免与用户定义的实体路径冲突。

可用性

模式	Swagger UI
development	启用
production	禁用

生产模式下访问 /swagger 返回 404。

自定义 REST 路径与 OpenAPI

如果实体配置了自定义 rest.path，OpenAPI 文档中会使用自定义路径而非实体名。例如 "path": "shopping-cart/item" 在 OpenAPI 中显示为 /api/shopping-cart/item。

OpenAPI 生成规则

规则	说明
只生成启用 REST 的实体	rest.enabled: false 的实体不出现在 OpenAPI 中
只显示有权限的操作	该角色无权的 HTTP 方法被省略
只显示可访问的字段	被 fields.exclude 排除的字段不出现在 schema 中
路径自动生成	基于实体名或自定义 rest.path
存储过程的参数映射	存储过程参数在对应的请求 schema 中描述

下一步

• REST 端点 — 端点结构和 HTTP 方法完整参考。
• HTTP If-Match — 更新操作的条件控制。