关于OpenAI Schema规范传参的问题，辛苦老师解答一下

第7章关于OpenAI Schema规范传参的问题有一些地方不是很理解，辛苦老师指点一下：

{
    "description": "这是一个查询对应英文单词字典的工具",
    "server": "https://dict.youdao.com",
    "paths": {
        "/suggest": {
            "get": {
                "description": "根据传递的单词查询其字典信息",
                "operationId": "YoudaoSuggest",
                "parameters": [{
                    "name": "q",
                    "in": "query",
                    "description": "要检索查询的单词，例如love/computer",
                    "required": true,
                    "type": "str"
                }, {
                    "name": "doctype",
                    "in": "query",
                    "description": "返回的数据类型，支持json和xml两种格式，默认情况下json数据",
                    "required": false,
                    "type": "str"
                }]
            }
        }
    }
}

1. 我看演示的时候基本都是get请求且请求参数较简单，如果是post请求而且入参是一个比较复杂的json应该怎么传参呢？
2. 这个OpenAPI Schema是只适用于OpenAI的大模型还是说所有模型都适配？

十丈红尘 2024-11-14

源自：可视化编排开发-插件与知识库集成 1-11 OpenAPI规范解读与API插件设计思路

收起

1回答

泽辉呀 2024-11-14 20:36:56

一样的哦，无论是get还是post，都可以使用OpenAPI Schema来描述，只要每个参数的含义是清晰的（重点在于写描述），`post`方法的API工具，只需要将 `in` 设置成 `request_body` 即可，无论多么复杂的一个接口都可以使用OpenAPI Schema来描述，添加多一种 `type=object` 结构即可，这里的 object 就是 json 对象。

另外OpenAPI Schema描述是一种描述性语言，和具体的方法无关，和编程语言无关，也和OpenAI无关，全名是`OpenAPI Schema`，即`开放API结构描述`，只是一种描述性的标准而已。

例如，上面的案例改成 post 方法后，对应的调整：

{
    "description": "这是一个查询对应英文单词字典的工具",
    "server": "https://dict.youdao.com",
    "paths": {
        "/suggest": {
            "post": {
                "description": "根据传递的单词查询其字典信息",
                "operationId": "YoudaoSuggest",
                "parameters": [{
                    "name": "q",
                    "in": "request_body",
                    "description": "要检索查询的单词，例如love/computer",
                    "required": true,
                    "type": "str"
                }, {
                    "name": "doctype",
                    "in": "request_body",
                    "description": "返回的数据类型，支持json和xml两种格式，默认情况下json数据",
                    "required": false,
                    "type": "str"
                }]
            }
        }
    }
}

收起回答

提问者十丈红尘 #1

我刚才参考课程中的文档资料简单写了一个，感觉不太对的样子和课程的结构对不上：

{
    "description": "提供用户注册和初始配置设置的API。",
    "server": "https://dict.youdao.com",
    "paths": {
        "/register": {
            "post": {
                "description": "允许用户注册新账号并配置初始设置。",
                "operationId": "registerUser",
                "parameters": [{
                    "name": "q",
                    "in": "request_body",
                    "description": "要检索查询的单词，例如love/computer",
                    "required": [
                        "username",
                        "email",
                        "password"
                    ],
                    "type": "object"
                }],
                "properties": {
                    "username": {
                        "type": "string",
                        "description": "用户的唯一用户名",
                        "example": "johndoe"
                    },
                    "email": {
                        "type": "string",
                        "description": "用户的电子邮件地址",
                        "format": "email",
                        "example": "johndoe@example.com"
                    },
                    "password": {
                        "type": "string",
                        "description": "用户的密码，需至少8个字符",
                        "format": "password",
                        "example": "strongpassword123"
                    }
                }
            }
        }
    }
}

2024-11-14 21:00:09

提问者十丈红尘 #2

而且还有一个问题就是，我看课程的代码中ParameterType类型没有Object，如果我在这段OpenAPI Schema中添加一个Object类型后端代码能解析吗？我是不是需要把后端代码中这个地方也添加一个Object？

2024-11-14 21:02:34
泽辉呀回复提问者十丈红尘 #3

是的，要在后端中添加object类型，其实在python中，就是将字段类型声明成dict，你写的这个声明是标准的OpenAPI Schema规范，课程的规范是针对OpenAPI Schema进行了缩减，不需要写properties，全部参数都在parameters中完成声明（扩充出：name、in、description、required、type这四个参数）。

2024-11-14 21:51:49