插件允许智能 Microsoft 365 Copilot 副驾驶®使用 Web 服务并获取实时信息。 Copilot 使用此信息来扩展其技能。 使用插件，用户可以将业务线 (LOB) 系统中的实时数据引入 Copilot。
插件由 API 服务、其 OpenAPI 说明和清单文件组成。 插件清单告知 Copilot API 的功能。 插件清单包括 API 服务的 OpenAPI 说明。 OpenAPI 说明非常重要，因为它向 Copilot 介绍了如何连接到 API。 为了使用 Copilot 实现插件的最佳性能，请提供清晰而有意义的 OpenAPI 说明。
本文介绍使 OpenAPI 说明对扩展 Copilot 的插件有效的元素。
OpenAPI 说明元素
本部分介绍 OpenAPI 说明的元素以及如何针对 Copilot 优化它们。
OpenAPI 验证：第一步是验证 OpenAPI 说明是否遵循 OpenAPI 规范的规则。 可以使用 Hidi，这是一种命令行工具，可在其他用例中验证 OpenAPI 说明，或者选择的任何其他工具。 有效的 OpenAPI 说明不仅适用于 Copilot，而且还可确保 OpenAPI 说明可以与其他工具配合使用。
信息部分：说明字段在 OpenAPI 规范中是可选的，但它对于旨在扩展 Copilot 技能的 OpenAPI 说明至关重要。 Copilot 需要说明字段来了解 API 的作用以及何时使用插件。 从 OpenAPI 文档生成插件清单时，信息部分中的说明将用作插件清单的说明。 因此，必须始终有一个简短而明确的说明字段。 例如，下面是维修店 OpenAPI 说明的信息部分。
info:
title: Repair Service
description: A simple service to manage repairs for various items
version: 1.0.0
作 ID： 增强 OpenAPI 说明可用性的一种有用技术是为 API 提供的 API 路径和 HTTP 方法的每个组合添加 operationID 。 作 ID 是 API 中作的唯一标识符，由 Copilot 用来创建响应用户提示时执行的函数。
此外，添加 API 支持的每个作的有意义说明。 Copilot 根据用户的提示和插件说明选择使用插件后，它会搜索路径的说明，以确定用于满足用户请求的终结点。
作 ID 在调试期间显示为函数，以指示 Copilot 正在尝试执行哪些作。 下面是 OpenAPI 文档的示例和相应调试器输出的示例：
paths:
/repairs:
get:
operationId: listRepairs
summary: List all repairs
description: Returns a list of repairs with their details and images
调试器输出：
参数： 如果 API 支持的作采用参数，请在 OpenAPI 说明中包含参数。 为每个参数添加说明字段以简要描述它，并在必要时提供参数用法的示例。 Copilot 使用参数从用户向 API 发出请求的提示中获取所有必需的信息。
下面是一个示例：
parameters:
- name: assignedTo
in: query
description: The name or ID of the person or team to whom the repair is assigned.
schema:
type: string
required: false
反应： 明确定义每个作的所有可能的响应，包括成功和错误响应。 每个响应都必须具有状态代码及其表示内容的说明。 包含响应示例可帮助 Copilot 了解 API 的预期内容。
responses:
'200':
description: A list of repairs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Repair'
examples:
example1:
value:
[
{
"id": "1",
"item": "Laptop",
"status": "In Progress",
"assignedTo": "John Doe"
}
]
'404':
description: No repairs found
'500':
description: Server error