组件 - Apidog Docs

通常在 API 设计中，由于不同端点对输出数据的需求不同，成功的 200 OK 响应往往会因端点而异；而 400 Bad Request 和 404 Not Found 等错误响应则倾向于在不同端点之间保持一致。

Apidog 通过其 响应组件 功能巧妙地解决了这种共性问题。该功能允许复用预定义的错误响应，从而使 API 文档编写过程更加高效，并使 API 行为更加一致。

OAS 兼容性

Apidog 中的响应组件功能与 OAS 中的 Components 兼容。

添加响应组件

在 APIs 模块左侧目录树中，导航到组件部分，然后点击 Responses 下的 新建响应 来创建新的响应组件。

创建响应组件类似于在定义端点时指定响应部分，包含 HTTP 状态码、Content type、Schema 和 Examples。如需详细指导，请参阅端点基础中的响应部分。

默认添加到新端点中：当选择为 “Yes” 时，此组件将默认自动包含在项目中所有新建端点中。

INFO

现有端点不受此设置影响。

在端点的 Response 部分，你可以引用预定义的响应组件。

关于被引用组件的要点：

被引用的响应组件无法在端点内修改。你必须对原始响应组件进行更改。所做的任何修改都会影响所有引用该组件的端点。

如果你希望修改已在端点中被引用的响应组件，可以对其进行解除引用。解除引用会将该响应转变为常规的可编辑响应，并且响应组件的更改将不再影响它。

在一个端点中，一个组件只能被引用一次；同一组件的多个实例不能在同一端点中共存。

你可以将现有响应组件批量添加到所选端点，或从所选端点中批量移除此组件。

注意事项：

如果所选端点已包含此响应组件，则不会再次添加。

如果所选端点不包含此响应组件，则移除操作不会生效。

许多公司会为其响应制定标准化结构。在这种情况下，你可以利用默认响应模板将公司的固定结构作为默认响应模板进行维护。

在左侧目录树的组件部分下，你可以访问并使用默认响应模板功能。

创建新端点时，此模板的内容会被用作初始响应。

主要特性：

对默认响应模板所做的更改只会影响新端点，现有端点将不受影响。

只有一个默认响应模板，不能添加或删除。

初始默认响应模板是一个 200 Success Response，Content type 为 JSON，数据结构为空 Object 节点。

Q：我可以将响应组件用作默认响应吗？

A：不可以，响应组件旨在用于 400、404 以及类似状态码等通用错误响应。如果你需要使用固定的默认响应，请使用默认响应模板。