Dify自定义工具例子

1.天气（JSON）

{
"openapi": "3.1.0",
"info": {
"title": "Get weather data",
"description": "Retrieves current weather data for a location.",
"version": "v1.0.0"
},
"servers": [
{
"url": "https://weather.example.com"
}
],
"paths": {
"/location": {
"get": {
"description": "Get temperature for a specific location",
"operationId": "GetCurrentWeather",
"parameters": [
{
"name": "location",
"in": "query",
"description": "The city and state to retrieve the weather for",
"required": true,
"schema": {
"type": "string"
}
}
],
"deprecated": false
}
}
},
"components": {
"schemas": {}
}
}

这段代码是一个OpenAPI规范的JSON文件，用于描述一个获取天气数据的API。总的来说，这个API允许用户查询特定位置的天气数据。

• "openapi": "3.1.0"：这表示使用的OpenAPI规范的版本是3.1.0。
• "info"：这部分提供了API的基本信息，包括标题、描述和版本。
• "servers"：这部分列出了API的服务器URL。
• "paths"：这部分定义了API的路径和操作。在这个例子中，有一个GET操作，路径是/location，用于获取特定位置的天气。这个操作需要一个名为location的查询参数，这个参数是必需的，类型是字符串。
• "components"：这部分用于定义API中使用的模式，但在这个例子中，它是空的。

在OpenAPI规范中，parameters是一个数组，用于定义API操作的输入参数。parameters定义了一个名为location的查询参数，这个参数是必需的，类型是字符串。每个参数都是一个对象，包含以下属性：

• "name"：参数的名称。
• "in"：参数的位置。可以是"query", "header", "path"或"cookie"。
• "description"：参数的描述。
• "required"：如果为true，则此参数是必需的。
• "schema"：参数的数据类型。

重点介绍下参数的位置，4种情况如下所示：

• header参数，用于在请求头中传递API密钥。
• path参数，用于在URL路径中指定要检索的对象的ID。
• cookie参数，用于在cookie中传递用户的会话ID。
• query参数，附加在URL后面的参数，通常用于提供信息过滤。

创建自定义工具界面：

测试工具接口界面：

2.宠物商店（YAML）

# Taken from https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/petstore.yaml
openapi: "3.0.0"
info:
version: 1.0.0
title: Swagger Petstore
license:
name: MIT
servers:
- url: https://petstore.swagger.io/v1
paths:
/pets:
get:
summary: List all pets
operationId: listPets
tags:
- pets
parameters:
- name: limit
in: query
description: How many items to return at one time (max 100)
required: false
schema:
type: integer
maximum: 100
format: int32
responses:
'200':
description: A paged array of pets
headers:
x-next:
description: A link to the next page of responses
schema:
type: string
content:
application/json:    
schema:
$ref: "#/components/schemas/Pets"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
post:
summary: Create a pet
operationId: createPets
tags:
- pets
responses:
'201':
description: Null response
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/pets/{petId}:
get:
summary: Info for a specific pet
operationId: showPetById
tags:
- pets
parameters:
- name: petId
in: path
required: true
description: The id of the pet to retrieve
schema:
type: string
responses:
'200':
description: Expected response to a valid request
content:
application/json:
schema:
$ref: "#/components/schemas/Pet"
default:
description: unexpected error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
Pet:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
tag:
type: string
Pets:
type: array
maxItems: 100
items:
$ref: "#/components/schemas/Pet"
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string

pet.yaml 是一个 OpenAPI 规范文件，用于描述和定义一个名为 "Swagger Petstore" 的 API 的接口。这个文件使用了 YAML 格式，它是一种用于编写配置文件的人类可读的数据序列化标准。这个文件为开发者提供了一个清晰的 API 接口定义，使得开发者可以知道如何与 "Swagger Petstore" API 进行交互。文件中的主要部分包括：

• openapi: 这个字段指定了使用的 OpenAPI 规范的版本，这里是 "3.0.0"。
• info: 这个部分提供了 API 的基本信息，包括版本、标题和许可证。
• servers: 这个部分定义了 API 的服务器 URL。
• paths: 这个部分定义了 API 的所有路径和操作。例如，/pets 路径有两个操作：get 和 post。get 操作用于列出所有宠物，post 操作用于创建一个新的宠物。每个操作都有自己的参数、响应和其他详细信息。
• components: 这个部分定义了可重用的模式（schemas），这些模式可以在 paths 部分中引用。例如，Pet、Pets 和 Error 模式。

将上述YAML文件转换为JSON格式：

{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"license": {
"name": "MIT"
}
},
"servers": [
{
"url": "https://petstore.swagger.io/v1"
}
],
"paths": {
"/pets": {
"get": {
"summary": "List all pets",
"operationId": "listPets",
"tags": ["pets"],
"parameters": [
{
"name": "limit",
"in": "query",
"description": "How many items to return at one time (max 100)",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "A paged array of pets",
"headers": {
"x-next": {
"description": "A link to the next page of responses",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pets"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Create a pet",
"operationId": "createPets",
"tags": ["pets"],
"responses": {
"201": {
"description": "Null response"
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/pets/{petId}": {
"get": {
"summary": "Info for a specific pet",
"operationId": "showPetById",
"tags": ["pets"],
"parameters": [
{
"name": "petId",
"in": "path",
"required": true,
"description": "The id of the pet to retrieve",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Expected response to a valid request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pet"
}
}
}
},
"default": {
"description": "unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Pet": {
"type": "object",
"required": ["id", "name"],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
"Pets": {
"type": "array",
"maxItems": 100,
"items": {
"$ref": "#/components/schemas/Pet"
}
},
"Error": {
"type": "object",
"required": ["code", "message"],
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
}
}
}
}
}
}

3.空白模板

{
"openapi": "3.1.0",
"info": {
"title": "Untitled",
"description": "Your OpenAPI specification",
"version": "v1.0.0"
},
"servers": [
{
"url": ""
}
],
"paths": {},
"components": {
"schemas": {}
}
}

注解：貌似JSON格式看上去更加直观。

参考文献

[1] OpenAPI Specification：https://swagger.io/specification/

普通人的AI入门指南

帮助你以低成本、零基础学会如何利用AI工具。AI就像办公软件一样，是每个人的必备技能。 掌握AI会让你在求职中占据优势，在未来的工作和学习中事半功倍。

查看详情>