Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refreshing the openapi guide content for public preview #10

Merged
merged 1 commit into from
Aug 21, 2024
Merged

refreshing the openapi guide content for public preview #10

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/openapi-document-guidance.md
View file
Open in desktop
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
Loading