Cómo hacer que un documento de OpenAPI sea eficaz para ampliar Copilot

Los complementos permiten Microsoft Copilot trabajar con servicios web y obtener información en tiempo real. Copilot usa esta información para ampliar sus aptitudes. Con un complemento, un usuario puede llevar datos en tiempo real desde su sistema de línea de negocio (LOB) al Copilot.

Un complemento se compone de un servicio de API, su descripción de OpenAPI y un archivo de manifiesto. El manifiesto del complemento informa a Copilot sobre las funcionalidades de la API. El manifiesto del complemento incluye una descripción de OpenAPI para el servicio de API. La descripción de OpenAPI es importante porque describe a Copilot cómo conectarse a la API. Para un rendimiento óptimo del complemento con Copilot, proporcione una descripción clara y significativa de OpenAPI. En este documento se explican los elementos que hacen que una descripción de OpenAPI sea efectiva para un complemento que extiende Copilot.

Aquí, se supone que tiene una API y una descripción de OpenAPI para ella.

Validación de OpenAPI: un buen primer paso es comprobar que la descripción de OpenAPI sigue las reglas de la especificación de OpenAPI. Puede usar Hidi, una herramienta de línea de comandos que puede validar las descripciones de OpenAPI entre otros casos de uso o cualquier otra herramienta que prefiera. Una descripción válida de OpenAPI no solo funciona bien con Copilot, sino que también se asegura de que la descripción de OpenAPI puede funcionar con otras herramientas.

La sección de información: El campo de descripción es opcional en la especificación de OpenAPI, pero es esencial para una descripción de OpenAPI que está pensada para ampliar las aptitudes de Copilot. Copilot necesita el campo de descripción para saber qué hace la API y cuándo usar el complemento. Al generar un manifiesto de complemento a partir de un documento de OpenAPI, la descripción de la sección de información se usa como descripción del manifiesto del complemento. Por lo tanto, es importante tener siempre un campo de descripción breve y claro. Por ejemplo, esta es una sección de información de una descripción de OpenAPI de una tienda de reparaciones.

info:
  title: Repair Service
  description: A simple service to manage repairs for various items
  version: 1.0.0

Identificadores de operación: Una técnica útil para mejorar la facilidad de uso de una descripción de OpenAPI es agregar una operationID para cada combinación de ruta de acceso de API y método HTTP que ofrece la API. Los identificadores de operación son identificadores únicos de una operación en la API y Copilot los usa para crear funciones que se ejecutan al responder al aviso de un usuario.

Además, agregue una descripción significativa de cada operación admitida por la API. Después de que Copilot decida usar un complemento en función del símbolo del usuario y de la descripción del complemento, busca en las descripciones de las rutas de acceso para determinar el punto de conexión que se usará para satisfacer la solicitud del usuario.

Los identificadores de operación se muestran durante la depuración como funciones para indicar qué operaciones intenta ejecutar Copilot. Este es un ejemplo de un documento de OpenAPI y un ejemplo de la salida del depurador correspondiente:

paths:
  /repairs:
    get:
      operationId: listRepairs
      summary: List all repairs
      description: Returns a list of repairs with their details and images

Salida del depurador:

Parámetros: Si una operación compatible con la API toma parámetros, incluya los parámetros en la descripción de OpenAPI. Incluya un campo de descripción para que cada parámetro lo describa brevemente y, cuando sea necesario, proporcione un ejemplo del uso del parámetro. Copilot usa los parámetros para obtener toda la información necesaria de la solicitud de un usuario para realizar una solicitud a la API.

Aquí le mostramos un ejemplo:

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

Respuestas: Defina claramente todas las respuestas posibles para cada operación, incluidas las respuestas correctas y de error. Cada respuesta debe tener un código de estado y una descripción de lo que representa. Incluir ejemplos de respuestas ayuda a Copilot a comprender qué esperar de la 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