端点基础

在 Apidog 中，设计和设置 API 端点是创建稳健且高效 API 的基础步骤。

建议按照 OpenAPI Specification (OAS) 来设计端点，以确保与 OpenAPI 生态系统中的各种工具和服务顺畅兼容。偏离 OAS 可能会在使用符合 OpenAPI 的工具和服务时导致兼容性问题。

创建端点

要在 APIs 模块中创建新的端点，请点击 New Endpoint 按钮。

一个清晰且完整的端点应包含以下元素：

端点路径

请求方法

端点元数据

请求

响应和示例

设计优先模式

请求优先模式

界面模式

Apidog 的端点界面有两种模式：用于 API 设计优先的 设计优先模式，以及用于代码优先方法的 请求优先模式。你可以在界面左下角切换模式。了解更多关于设计优先模式/请求优先模式的信息。

端点路径

端点路径是 API 可与外部应用程序交互的特定地址。客户端将使用它来访问 API 服务。

Apidog 遵循 OpenAPI Specification 的方式。你无需为每个端点编写完整 URL，只需输入路径（例如 /users）。基础 URL 在环境中设置，Apidog 会在向端点发起请求时自动添加它。

为了与 OpenAPI 标准保持一致，Apidog 还建议所有路径都以 / 开头。这能让你的 API 设计保持清晰、有序，并确保你充分受益于 Apidog 的功能。

为什么路径要以 / 开头

建议以 / 开头，以遵循 OAS。如果路径未以 / 开头，在使用 OpenAPI 生态系统中的工具时可能会导致各种兼容性问题。

此外，在路径开头使用 / 可以启用 URL pattern mock 功能，这对于 Apidog 中的测试和验证非常重要。

请求方法

请求方法决定客户端如何与服务器端资源交互。每种方法都有其自身的语义，并决定服务器的响应。在设计 API 时，应根据业务需求选择最合适的请求方法，以有效执行预期操作。

以下是常用的 API 请求方法：

方法	描述
GET	获取指定资源且无副作用。使用查询参数传输数据。
POST	提交数据进行处理，可能产生副作用。数据通常在请求主体中发送。
PUT	完整更新或替换指定资源。
DELETE	删除指定资源。
OPTIONS	查询目标资源支持的 HTTP 方法。
HEAD	类似于 GET，但只获取响应头部。适用于在不下载资源内容的情况下检查资源是否存在以及是否被修改。
PATCH	更新指定资源的部分信息。
TRACE	返回服务器收到的请求。主要用于调试和诊断。
CONNECT	建立到服务器的隧道，通常用于代理服务器的请求转发。

端点元数据

在 Apidog 中，端点带有默认元数据字段，用于定义和管理 API 的文档、可访问性和生命周期。

以下是每个默认元数据字段的简要概述：

字段	描述
名称	描述端点功能的名称。
状态	默认状态为“Developing”。你可以修改它以反映不同阶段，例如 Testing 或 Production。了解更多关于端点状态的信息。
维护者	指定负责该端点的 Apidog 团队成员。从你的账号中选择用户来分配此角色。
标签	用于分类或描述端点的关键词或短语。你可以创建新标签或从现有标签中选择。
服务	端点路径将追加到的基础 URL。默认设置为“Inherit from parents”，但可以通过环境设置手动指定。了解更多关于环境和服务的信息。
OperationId	唯一标识符（OAS 中的 operationId），用于在 API 中区分此操作。
描述	关于端点目的和用法的详细信息，支持 Markdown 以增强格式化效果。

自定义字段

除了为端点提供的标准元数据字段外，你还可以灵活地添加自定义字段，进一步丰富端点的元数据。

请求

请求参数

请求参数是可随请求一起传递的选项，用于控制数据返回或修改服务器的响应。

请求参数包括查询参数、路径参数、头部参数和主体参数。

查询参数

查询参数是追加在 URL 末尾问号 ? 之后的键值对，并使用 & 分隔，如下所示：?id=2&status=available。它们用于筛选、排序或修改 API 端点的输出。

INFO

在 Apidog 中，为了清晰和便于组织，查询参数会在单独的部分中描述。不过，在发送请求时，这些查询参数会以上述方式与端点路径拼接。

路径参数

路径参数是端点 URL 本身的一部分，用于标识 API 中的特定资源或实体。

在 Apidog 中，路径参数使用 花括号 表示，而不是冒号。正确示例：/pets/{id}，错误示例：/pets/:id。

如果你需要在路径参数中使用变量，推荐的做法是在 URL 中将其定义为 {parameter}，然后使用 {{variable}} 作为参数值。例如：

推荐：将变量放在路径参数值中

不推荐：将变量直接放在 URL 中

不要混淆 {parameter} 和 {{variable}}

{parameter}：单花括号表示 Apidog 中的路径参数。路径参数是 URL 路径中的占位符，在访问 API 端点时会动态变为特定值。

{{variable}}：双花括号包含请求中的变量。发送请求时，这些变量可以被替换为实际值，从而在 API 交互中实现动态且可自定义的输入。

为什么不要在路径中使用 {{variable}}

使用 {{variable}} 不符合 OAS。遵循 OAS 可与 OpenAPI 生态系统中的多种工具无缝集成。

在路径中使用 {{variable}} 将导致无法使用 Apidog 中的 URL pattern mock 功能。

头部参数

头部参数提供有关所发出请求的附加信息，通常用于身份验证、内容类型和其他元数据。

了解更多

了解更多关于头部参数的信息。

主体参数

主体参数包含要在请求主体中发送的数据，通常用于 POST、PUT 和 PATCH 请求，以创建或更新资源。数据通常以 JSON 或 XML 格式发送。

了解更多

了解更多关于主体参数的信息。

描述参数

参数应使用其名称、类型（string、integer、boolean 等）、必要性（必填或可选）以及任何默认值或约束进行描述。

描述参数时，通常会使用以下关键属性：

属性	描述
名称	指定所描述参数的名称。这是必填字段，应准确表示所定义的参数。
类型	指定参数值的数据类型。常见值包括 `string`、`number`、`integer`、`boolean`、`array`、`object` 等。此属性有助于定义参数值的格式和结构。
描述	提供有关参数的简要说明或文档。它帮助用户理解参数的目的和用法。
必填	指定该参数对于 API 请求是否为必需项。它是一个布尔值（`true` 或 `false`），表示请求中是否必须包含该参数。
高级设置	定义参数的数据类型、格式和约束。它允许你提供有关参数值预期结构和内容的详细信息。

类型编辑器

你可以使用类型编辑器高效修改参数的高级设置。了解更多关于类型编辑器的信息。

Schema

当主体参数类型为 JSON 或 XML 时，需要设置数据结构。数据结构可以引用 schema。

了解更多

有关 schema 的详细信息，请参阅 Schema。

响应和示例

向 API 发送请求后，服务器会返回响应。定义预期响应并提供说明性示例，是增强与你的 API 对接的开发者理解度和可用性的关键步骤。

返回响应的定义主要包括以下部分：

组件	描述
HTTP 状态码	确定端点可能返回的所有潜在响应状态，包括标准响应，如 200 (OK)、404 (Not Found) 或 500 (Server Error)。
数据格式	定义 API 针对每个状态码返回的响应格式。可以是 `JSON`、`XML`、`HTML`、`Raw`、`Binary` 或任何其他合适的格式。
Schema	对于携带数据的响应（主要是 200 状态），详细说明响应载荷的结构。这包括指定类型、嵌套对象、可选字段和数组。清晰的定义有助于客户端开发者了解应预期哪些数据以及如何解析这些数据。只有 `JSON` 和 `XML` 可以配置 schema。有关详细信息，请参阅 Schema。
示例	提供响应示例对于说明 API 在真实场景中的行为至关重要。示例理想情况下应是当端点被预定义请求命中时服务器返回的一组样本数据。它应反映响应 schema 所定义的结构、数据格式和类型。

添加响应

通常，建议在 API 文档中为每个端点至少定义一个成功响应和一个错误响应。这种做法可确保覆盖各种潜在结果，让开发者清楚了解 API 在不同场景下的行为。

点击 Responses 模块右上角的 + Add 按钮来添加响应。

在 API 设计中，成功的 200 OK 响应通常会因各端点不同的输出数据需求而有所差异，而错误响应（如 400 Bad Request 和 404 Not Found）往往在不同端点之间保持一致。Apidog 通过其响应组件功能巧妙地处理了这种共性，该功能允许复用预定义的错误响应，使 API 文档编写过程更加高效，并让 API 行为更加一致。

响应组件

了解更多关于响应组件的信息。

如果不需要响应组件，你可以选择 Add Blank Response，为各个端点定义唯一的响应。

添加响应示例

点击 "Add Example"，在 Apidog 中包含响应示例。

单个响应可以容纳多个不同的示例。添加示例时，请为示例提供名称以及对应的响应数据。

自动生成示例

点击 Generate Automatically 后，Apidog 将根据响应 schema 定义生成合理的响应数据。

预览端点

完成端点规范后，点击 "Save" 保存更改。然后，切换到 "API" 标签页，预览你刚刚配置的端点。

创建端点#

端点路径#

请求方法#

端点元数据#

请求#

请求参数#

查询参数#

路径参数#

头部参数#

主体参数#

描述参数#

Schema#

响应和示例#

添加响应#

添加响应示例#

自动生成示例#

预览端点#

创建端点

端点路径

请求方法

端点元数据

请求

请求参数

查询参数

路径参数

头部参数

主体参数

描述参数

Schema

响应和示例

添加响应

添加响应示例

自动生成示例

预览端点