注释
本节中描述的数据 API 生成器 2.0 功能目前处于预览状态，在正式发布之前可能会更改。 有关详细信息，请参阅 版本 2.0 中的新增功能。
OpenAPI 规范是一种与语言无关的标准，用于记录 HTTP API。 数据 API 生成器支持 OpenAPI，方法是：
- 为运行时配置中定义的所有已启用 REST 的实体生成元数据
- 将该元数据编译为有效的 OpenAPI 架构
- 通过可视化界面（Swagger）或序列化的 JSON 文件展示架构
- 筛选架构以仅显示给定角色可访问的 HTTP 方法和字段
OpenAPI 说明文档
数据 API 生成器使用运行时配置和每个已启用 REST 的实体的数据库元数据生成 OpenAPI 说明文档。
该架构是使用 OpenAPI.NET SDK 构建的，符合 OpenAPI 规范 v3.0.1。 输出为 JSON 文档。
可以在以下位置访问 OpenAPI 文档：
GET /{rest-path}/openapi
注释
默认情况下， rest-path 为 api。 此值是可配置的。 有关详细信息，请参阅 REST 配置 。
权限感知的 OpenAPI 接口
从 DAB 2.0 开始，OpenAPI 文档反映了为每个实体配置的实际权限。 生成的架构 只 显示给定角色可以访问的方法和字段，而不是记录每个可能的 HTTP 方法。
权限如何映射到 HTTP 方法
DAB 将实体权限转换为 OpenAPI 文档中的 HTTP 方法可见性：
| 权限操作 | 显示的 HTTP 方法 |
|---|---|
read |
GET |
create |
POST |
create + update |
PUT、PATCH |
delete |
DELETE |
例如，如果 anonymous 角色仅对 Book 实体具有 read 权限，则匿名角色的 OpenAPI 文档仅显示 /api/Book 的 GET 操作。 将完全省略POST、PUT、PATCH和DELETE操作。
字段级筛选
权限包括字段级 include 或 exclude 规则时，OpenAPI 架构反映这些约束。 只有角色可访问的字段才会出现在请求和响应架构中。 该筛选功能使用户能够准确了解 API 针对其角色接受和返回的数据。
特定于角色的 OpenAPI 路径
DAB 提供针对特定角色的 OpenAPI 端点，以便检查任何已配置角色的架构。
GET /{rest-path}/openapi
GET /{rest-path}/openapi/anonymous
GET /{rest-path}/openapi/authenticated
GET /{rest-path}/openapi/admin
基 /openapi 路径返回默认匿名视图。 每个角色特定的路径返回基于该角色权限的筛选后的架构。
重要
特定于角色的 OpenAPI 路径（/openapi/{role}） 仅在开发模式下可用。 在生产模式下，禁用这些终结点以防止角色枚举。 在生产模式下，只有基本 /openapi 路径可用。
注释
如果在运行时配置的任何位置都没有为角色配置实体权限，则特定于角色的终结点将返回 404 Not Found。 至少一个实体上至少有一个permissions条目的角色才能生成 OpenAPI 文档。
示例
请考虑此权限配置：
{
"entities": {
"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显示在/api/Book上进行的GET、POST、PUT、PATCH和DELETE操作，包含所有字段。
Swagger UI
Swagger UI 根据 OpenAPI 架构提供基于 Web 的 API 的交互式视图。
在 Development 模式下，Data API 生成器暴露出 Swagger UI 位于：
GET /swagger
此终结点未嵌套在 rest-path 以下位置，以避免与用户定义的实体冲突。