From 35843e8cf86fecce1bf0dbc1ffd2d3a23f97b532 Mon Sep 17 00:00:00 2001 From: njaci1 Date: Tue, 2 Jul 2024 21:34:00 +0300 Subject: [PATCH] refreshing the openapi guide content for jul15 --- docs/openapi-document-guidance.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/openapi-document-guidance.md b/docs/openapi-document-guidance.md index 1a6b76e..16bac91 100644 --- a/docs/openapi-document-guidance.md +++ b/docs/openapi-document-guidance.md @@ -11,13 +11,13 @@ ms.date: 05/21/2024 Plugins let Microsoft Copilot work with web services and get real-time information. Copilot uses this information to extend its skills. With a plugin, a user can bring real-time data from their line of business (LOB) system on to the Copilot. -A plugin is comprised of a web service, its OpenAPI description, and a manifest file. The plugin manifest informs Copilot about the plugin's capabilities. The plugin manifest includes an OpenAPI description for the web service. The OpenAPI description is important because it describes to Copilot how to connect to the web service. For optimal plugin performance with Copilot, provide a clear and meaningful OpenAPI description. This document explains the elements that make an OpenAPI description effective for a plugin that extends Copilot. +A plugin is comprised of an API service, its OpenAPI description, and a manifest file. The plugin manifest informs Copilot about the API's capabilities. The plugin manifest includes an OpenAPI description for the API service. The OpenAPI description is important because it describes to Copilot how to connect to the API. For optimal plugin performance with Copilot, provide a clear and meaningful OpenAPI description. This document explains the elements that make an OpenAPI description effective for a plugin that extends Copilot. -Here, we presume that you have a web service and an OpenAPI description for the web service. +Here, we presume that you have an API and an OpenAPI description for it. **OpenAPI Validation**: A good first step is to verify that your OpenAPI description follows the rules of the [OpenAPI Specification](https://swagger.io/resources/open-api/). You can use [Hidi](https://github.com/microsoft/OpenAPI.NET/blob/vnext/src/Microsoft.OpenApi.Hidi/readme.md), a command line tool that can validate OpenAPI descriptions among other use cases, or any other tool of choice. A valid OpenAPI description not only works well with Copilot but also makes sure that your OpenAPI description can work with other tools. -**The info section**: The description field is optional in the OpenAPI specification, but it's essential for an OpenAPI description that is meant to extend Copilot skills. Copilot needs the description field to know what the API does and when to use the plugin. Always have a description field and make it brief but clear. For example, here's an info section of a repairs shop web service OpenAPI description. +**The info section**: The description field is optional in the OpenAPI specification, but it's essential for an OpenAPI description that is meant to extend Copilot skills. Copilot needs the description field to know what the API does and when to use the plugin. When generating a plugin manifest from an OpenAPI document, the description in the info section is used as the description for the plugin manifest. It is thus important to always have a description field that is brief and clear. For example, here's an info section of a repairs shop OpenAPI description. ```yaml info: