OpenapiSchema工具

1. 创建方式

• 登录智能体应用开发平台

• 点击工具页面中右侧的创建工具按钮，点击OPENAPI Schema工具。

• 输入工具配置信息进行工具创建，完成创建的工具支持在应用中使用。

• 工具名称：用户可自定义工具名称

• Schema：

  • 支持 OpenAPI / Swagger 规范。你可以将 OpenAPI schema 内容直接粘贴或从 URL 内导入。
  • 工具目前支持两种鉴权方式：无鉴权 和 API Key。

• 工具列表：

  • 在导入 Schema 内容后系统会主动解析文件内的参数，并可预览工具具体的参数、 方法、路径。您也可以在此对工具参数进行测试。
    

2. 创建示例

• 部分服务商会直接提供

  • 需要仔细查看一下对方的文档, 关键字为 OpenAPI Schema或OpenAPI YAML:
    
  • 如果没有, 可以使用大模型来生成对应的OpenAPI YAML文件:
    
  • 将文档内容保存下来, 发送给大模型, 示例:
    • 天气查询-高级 API 文档-开发指南-Web服务 API | 高德地图API
    • 从图中可见, 文档内容排版混乱, 对于大模型不友好 需要手工修改。
      
  • 手工修改后：
    • 天气查询API服务地址

  URL	请求方式
  https://restapi.amap.com/v3/weather/weatherInfo?parameters	GET

  • parameters 代表的参数包括必填参数和可选参数。所有参数均使用和号字符(&)进行分隔。下面的列表枚举了这些参数及其使用规则。
    • 请求参数

  参数名	含义	规则说明	是否必须	缺省值
  key	请求服务权限标识	用户在高德地图官网申请 web 服务 API 类型 KEY	必填	无
  city	城市编码	输入城市的 adcode，adcode 信息可参考城市编码表	必填	无
  extensions	气象类型	可选值：base/all base: 返回实况天气 all: 返回预报天气	可选	无
  output	返回格式	可选值：JSON、XML	可选	JSON

  • 返回结果参数说明
    • 实况天气每小时更新多次，预报天气每天更新3次，分别在8、11、18点左右更新。由于天气数据的特殊性以及数据更新的持续性，无法确定精确的更新时间，请以接口返回数据的reporttime 字段为准。天气结果对照表>>

  一级字段	二级字段	三级字段	含义	规则说明
  status	-	-	返回状态	值为 0 或 1；1：成功；0：失败
  count	-	-	返回结果总数目	-
  info	-	-	返回的状态信息	-
  infocode	-	-	返回状态说明， 10000 代表正确
  lives	-	-	实况天气数据信息	-
  	province	-	省份名	-

| | city | - | 城市名 | - |
| | adcode | - | 区域编码 | - |
| | weather | - | 天气现象（汉字描述） | - |
| | temperature | - | 实时气温，单位：摄氏度 | - |
| | winddirection | - | 风向描述 | - |
| | windpower | - | 风力级别，单位：级 | - |
| | humidity | - | 空气湿度 | - |
| | reporttime | - | 数据发布的时间 | - |
| forecast | - | - | 预报天气信息数据 | - |
| | city | - | 城市名称 | - |
| | adcode | - | 城市编码 | - |
| | province | - | 省份名称 | - |
| | reporttime | - | 预报发布时间 | - |
| | casts | - | 预报数据 list 结构，元素 cast，按顺序为当天、第二天、第三天的预报数据 | - |
| | | date | 日期 | - |
| | | week | 星期几 | - |
| | | dayweather | 白天天气现象 | - |
| | | nightweather | 晚上天气现象 | - |
| | | daytemp | 白天温度 | - |
| | | nighttemp | 晚上温度 | - |
| | | daywind | 白天风向 | - |
| | | nightwind | 晚上风向 | - |
| | | daypower | 白天风力 | - |
| | | nightpower | 晚上风力 | - |

• 使用大模型生成YAML配置文件
  • 将文档内容发送至大模型, Prompt为: 请根据这个API说明文档, 生成OPENAPI YAML配置文件:{ 文档内容 }
    
  • 大模型返回:
    
  • 需要文档内容比较规整, 如果不够规整, 需要手动处理:
    • i.必查项清单
      • 所有路径参数是否在parameters中定义？
      • 请求/响应示例与文档是否一致？
      • securitySchemes 是否正确定义（如OAuth作用域）？
      • 错误响应（4xx/5xx）是否完整？
    • ii. 以及可以使用脚本或在线工具, 手工校验合理性:
      • 在线工具: Swagger Editor

````pip install pyyaml openapi-spec-validator** ** # npm install -g @stoplight/spectral-cli*** ** import os ** ** import yaml ** ** import subprocess ** ** from openapi_spec_validator ** ** import validate_spec ** ** from openapi_spec_validator.exceptions ** ** import OpenAPIValidationError ** ** def load_yaml_file(file_path): ** ** try : ** ** with open (file_path, 'r' , encoding = 'utf-8' ) ** ** as f: data = yaml.safe_load(f) print ( "✅ YAML 语法检查通过" ) ** ** return data ** ** except yaml.YAMLError ** ** as e: print ( "❌ YAML 格式错误:" , e) ** ** return None** ** except Exception** ** as e: print ( "❌ 加载 YAML 文件时发生错误:" , e) ** ** return None** ** def validate_openapi_spec(spec): ** ** try : validate_spec(spec) print ( "✅ OpenAPI 规范校验通过" ) ** ** except OpenAPIValidationError ** ** as e: print ( "❌ OpenAPI 规范校验失败:" , e) ** ** except Exception** ** as e: print ( "❌ 其他异常:" , e) ** ** def run_spectral_lint(file_path): ** ** try : result = subprocess.run( [ "spectral" , "lint" , file_path], stdout = subprocess.PIPE, stderr = subprocess.PIPE, text = True ) ** ** if result.returncode == 0 : print ( "✅ Spectral 规则检查通过" ) ** ** else : print ( "❌ Spectral 报告如下：\n" ) print (result.stdout) ** ** except FileNotFoundError : print ( "⚠️ 未找到 Spectral，请确保已安装 `@stoplight/spectral-cli`" ) ** ** def main(file_path): print ( f"�� 正在校验: { file_path }\n{'-' * 50 } " ) spec = load_yaml_file(file_path) ** ** if spec: validate_openapi_spec(spec) print ( "-" * 50 ) run_spectral_lint(file_path) ** ** if name == "__main__" : ** ** import argparse parser = argparse.ArgumentParser(description = "验证 OpenAPI YAML 文件" ) parser.add_argument( "file" , help = "要验证的 OpenAPI YAML 文件路径" ) args = parser.parse_args() main(args. file )

• 在导入 Schema 内容后系统会主动解析文件内的参数，并可预览工具具体的参数、 方法、路径。您也可以在此对工具参数进行测试。
• 输入后会出现测试按钮:
• 点击测试按钮, 输入必要信息, 查看返回结果:
  
• 测试通过后点击保存按钮, 新的工具会出现在”自定义”栏中。