如何定义插件接口协议

我们支持OpenAPI v3协议来提供对于插件接口的描述。关于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: array
          items:
            type: string
          description: The list 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.

上述示例中各项内容的解释如下。

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：必填项

  • deprecated：是否弃用

  • allowEmptyValue：允许提交空值

  • schema：参数的类型

  • example：参数的示例

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

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

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: array
          items:
            type: string
          description: The list of todos.