路由与 CRUD

路由 是您的 API 的入口点。它们按资源分组，您可以手动编写，也可以从模型 生成。

定义一个路由

一个路由带有一个 方法、一个 路径、若干 参数 和若干 响应。路径 使用 Restorm 的 {{param}} 语法：一旦您在路径中输入 {{id}}，对应的参数就会 出现；移除它就会删除该参数。

参数

一个路由的 定义 选项卡列出它的参数 —— 路径 参数（从 {{param}} 占位符 创建）以及您用 添加参数 添加的 查询 / 请求头 参数。每个参数都带有一个 名称、一个位置（in）、是否 必需、一个描述，以及可选的一个 示例。

类型 单元格是一个组合框：一键选择一个原始类型（string、integer、number、 boolean），或设计的某个 命名枚举。对于更复杂的情形，选择 Advanced… 打开 一个小对话框，您可以在其中：

• 让参数成为一个 数组 并选择它的 元素类型（array<string>、……）—— 一个 多值查询参数；
• 在它未被命名枚举定型时，为它赋予 内联枚举值（允许的集合，以 chip 形式列出）；
• 提取为命名枚举 —— 将这些内联值提升为一个共享枚举（参见模型与枚举）。

一个参数还可以 关联到一个模型属性（模型链接 列），从而继承其类型，或被标记为 已弃用。每个参数 —— 它的类型、它的枚举、它的弃用状态 —— 都会进入所生成的文档以及 每一种协议投影。

生成 CRUD

从一个模型的设置中，生成 CRUD 一键创建一个以模型复数命名的路由组，包含六个 路由：

路由	方法与路径	响应
列出	GET /（分页）	200
获取	GET /{{id}}	200 · 404
创建	POST /	201
替换	PUT /{{id}}	200 · 404
更新	PATCH /{{id}}	200 · 404
删除	DELETE /{{id}}	204 · 404

列表是 分页的（偏移/offset，默认 20 项，最多 100 项）。每个 {{id}} 都会 自动 关联到模型的标识符。

生成 CRUD 对话框提供两个选项：

• 替换现有路由 —— 在您重新生成时避免重复。
• 用认证保护写入路由 —— 于是创建、替换、更新和删除要求一个令牌（bearer）， 而读取保持公开。

它还提醒您，CRUD 会 在每个协议中 提供服务：REST 路由、GraphQL 查询与变更、 gRPC 方法、OData 实体集和 SOAP 操作（参见将设计作为 mock 提供服务）。

生成搜索路由

对于每个标记为 searchable 的属性，生成搜索路由 会添加一个关联到模型 列表路由的查询参数（如果该路由尚不存在，则创建它）。

认证

认证在三个层级设置：设计的一个默认值、每个组的 需要认证，以及每个路由的 覆盖（它继承组的默认值）。可用的模式有 无、Bearer（JWT）、API 密钥 （请求头） 和 Basic。

标签

标签 为文档和 OpenAPI 导出将路由分组。它们存在于两个层级：一个路由带有它 自己的 标签（它的 定义 选项卡），而一个组带有 共享 标签（它的设置）， 应用于它所包含的每个路由。一个路由的有效标签是二者的 并集 —— 因此，对整个组 共有的标签，最好只在组上设置一次。当您把一个导入的 API 转换为设计时，一个被某个组 的每个路由共享的标签会被自动上提到该组。

弃用

一个路由（如同一个属性或一个参数）可以从它的 设置 中被标记为 已弃用。一个 已弃用的路由在路由列表和所生成的客户端中显示为 灰显，并在它的选项卡上带有一条 弃用提示。该标志会传播到每一种协议投影 —— OpenAPI 的 deprecated、GraphQL 的 @deprecated 指令、SOAP 和 gRPC 描述符，以及 OData 元数据 —— 从而让任何所提供协议 的使用者都能看到它。