插件接入指引

您可以方便地将已有的api接口包装为plugin，仅需提供以下两个文件：

• 元信息描述文件：ai-plugin.json

• API描述文件：openapi.yaml

将上述两个文件编写完成后，通过邮件提交给工作人员（dashscope@alibabacloud.com）进行录入确认。

元信息描述文件：ai-plugin.json

元信息描述文件ai-plugin.json描述了插件的基本信息，以下是一个示例，定义了一个管理待办事项的插件：

{
    "schema_version": "v1",
    "name_for_human": "待办事项插件",
    "name_for_model": "todo",
    "description_for_human": "用于管理待办事项列表的插件。您可以添加、删除和查看您的待办事项。",
    "description_for_model": "用于管理待办事项列表的插件。您可以添加、删除和查看您的待办事项。",
    "auth": {
        "type": "none"
    },
    "api": {
        "type": "openapi",
    },
    "logo_url": "http://localhost:3333/logo.png",
    "contact_email": "support@example.com"
}

插件基本信息

插件鉴权配置（auth字段）

不需要鉴权

默认不需要鉴权，可以填写如下auth信息或者不填。

"auth": {
  "type": "none"
}

服务级别token

服务级别token鉴权，调用插件时默认会在Header里加上(“Authorization”: “Bearer service_token”)，所有的用户调用使用同一个token。

"auth": {
  "type": "service_http",
  "authorization_type": "bearer",
  "verification_tokens": {
    "dashscope": "替换token信息"
  }
}

用户级别鉴权

用户级别token鉴权，用来实现第三方插件对dashscope平台的鉴权。外部用户通过sdk或dashscope管控台时需手动添加user token信息，dashscope内部调用插件时候会在请求Header里加上（“Authorization”: “Bearer user_token”）。

"auth": {
  "type": "user_http",
  "authorization_type": "bearer",
}

API描述文件：openapi.yaml

我们依照OpenAPI v3协议来提供对于插件API的描述。关于OpenAPI v3的详细字段，您可以参见： OpenAPI v3.0.3。

您可以通过编辑器来编辑和验证API描述文件的正确性。以下是一个示例。

openapi: 3.0.1
info:
  title: TODO Plugin
  description: A plugin that allows the user to create and manage a TODO list using ChatGPT. If you do not know the user's username, ask them first before making queries to the plugin. Otherwise, use the username "global".
  version: 'v1'
servers:
  - url: http://localhost:5003
paths:
  /todos/{username}:
    get:
      operationId: getTodos
      summary: Get the list of todos
      parameters:
      - in: path
        name: username
        schema:
            type: string
        required: true
        description: The name of the user.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getTodosResponse'
    post:
      operationId: addTodo
      summary: Add a todo to the list
      parameters:
      - in: path
        name: username
        schema:
            type: string
        required: true
        description: The name of the user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addTodoRequest'
      responses:
        "200":
          description: OK
    delete:
      operationId: deleteTodo
      summary: Delete a todo from the list
      parameters:
      - in: path
        name: username
        schema:
            type: string
        required: true
        description: The name of the user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deleteTodoRequest'
      responses:
        "200":
          description: OK

components:
  schemas:
    getTodosResponse:
      type: object
      properties:
        todos:
          type: string
          description: The content of todos.
    addTodoRequest:
      type: object
      required:
      - todo
      properties:
        todo:
          type: string
          description: The todo to add to the list.
    deleteTodoRequest:
      type: object
      required:
      - todo_idx
      properties:
        todo_idx:
          type: integer
          description: The index of the todo to delete.

以下将分别描述schema对应的信息。

openapi对象

指定使用的openapi版本

openapi: 3.0.1

info对象

info:
  title: TODO Plugin
  description: A plugin that allows the user to create and manage a TODO list using ChatGPT. If you do not know the user's username, ask them first before making queries to the plugin. Otherwise, use the username "global".
  version: 'v1'

• title： 标题

• description: API 描述

• version：版本号

servers对象

servers:
  - url: http://localhost:5003

• URL表示访问服务端的基础路径，即在访问接口前都会带上该参数。

paths 对象

paths:
  /todos/{username}:
    get:

paths表示对象包含真正的 API 信息内容，它的每个项都包含一个可操作的endpoint。

例如上述/todo/{username}包含GET/POST/DELETE三个操作接口，每个操作的接口包含如下的属性：

• tags：用于对 endpoint 进行分组的组名。

• summary：操作对象的摘要信息，最好限制在 5-10字以内，主要作为概览展示。

• description：操作对象的描述信息，尽可能的详细，展示细节信息。

• operationId：操作对象的唯一ID。

• parameters：该端点的请求参数对象，描述如下：

  • name：参数名称。

  • in：参数出现的位置，通常是 header，path，query，cookie。

  • description：参数的描述。

  • required：是否是必填的参数。

  • schema：参数的类型。

  • example：参数的示例。

• requestBody：请求主体的描述，还可以包含一个指向 components 的 $ref 指针。

• response：响应主体的描述，通常使用标准的 HTTP 状态码，可以包含指向 components的$ref指针。

一个简单的parameters示例

parameters:
  - name: user_name
    in: path
    description: The name of the user.
    required: false
    schema:
      type: string

一个包含多级json的requestBody示例

requestBody:
  content:
    application/json:
      schema:
        required:
          - data
        type: object
        properties:
          data:
            required:
              - input
            type: object
            properties:
              input:
                type: string
                description: XXXX

responses 对象

responses:
  "200":
    description: OK
    content:
    	application/json:
        schema:
          $ref: '#/components/schemas/getTodosResponse'

responses 用于描述接口的响应对象，直接使用常见的httpcode作为key值。

components 对象

在components中定义可重复使用的对象，以便其他对象使用 $ref 关键字直接引用和声明。

components:
  schemas:
    getTodosResponse:
      type: object
      properties:
        todos:
          type: string
          description: The content of todos.