Skip to content

Commit

Permalink
refreshing the openapi guide content for jul15
Browse files Browse the repository at this point in the history
  • Loading branch information
njaci1 authored Jul 2, 2024
1 parent e8c728c commit 35843e8
Showing 1 changed file with 3 additions and 3 deletions.
6 changes: 3 additions & 3 deletions docs/openapi-document-guidance.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down

0 comments on commit 35843e8

Please sign in to comment.