Documentation
¶
Overview ¶
概述 ¶
Package openapi 提供从 OpenAPI 规范自动生成 Agent 工具的能力。
该包解析 OpenAPI 3.x JSON 规范，将每个 API Operation 转换为 AgentFlow 可直接调用的 GeneratedTool，包含名称、描述、参数 Schema、 HTTP 方法和路径等完整信息。
核心接口/类型 ¶
- Generator — OpenAPI 工具生成器，负责加载规范和生成工具
- OpenAPISpec — 解析后的 OpenAPI 规范（Info / Servers / Paths）
- GeneratedTool — 生成的工具定义，包含 llm.ToolSchema 和 HTTP 调用信息
- GenerateOptions — 工具生成选项（BaseURL 覆盖、Tag 过滤、前缀等）
- Operation / Parameter / RequestBody / JSONSchema — OpenAPI 结构体映射
主要能力 ¶
- 规范加载：从 URL 加载 OpenAPI JSON 规范，内置缓存避免重复请求
- 工具生成：遍历 Paths 中的所有 Operation，自动生成 GeneratedTool 列表
- Tag 过滤：通过 IncludeTags / ExcludeTags 控制生成范围
- 参数映射：自动将 path / query / header 参数和 RequestBody 转换为 JSON Schema
- 安全传输：HTTP 请求使用 tlsutil.SecureHTTPClient
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GenerateOptions ¶
type GenerateOptions struct {
BaseURL string
IncludeTags []string
ExcludeTags []string
Prefix string
}
GenerateOptions configures tool generation.
type GeneratedTool ¶
type GeneratedTool struct {
Name string `json:"name"`
Description string `json:"description"`
Schema llm.ToolSchema `json:"schema"`
Method string `json:"method"`
Path string `json:"path"`
BaseURL string `json:"base_url"`
Parameters []Parameter `json:"parameters"`
RequestBody *RequestBody `json:"request_body,omitempty"`
}
GeneratedTool represents a tool generated from OpenAPI.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator generates tools from OpenAPI specifications.
func NewGenerator ¶
func NewGenerator(config GeneratorConfig, logger *zap.Logger) *Generator
NewGenerator creates a new OpenAPI tool generator.
func (*Generator) GenerateTools ¶
func (g *Generator) GenerateTools(spec *OpenAPISpec, opts GenerateOptions) ([]*GeneratedTool, error)
GenerateTools generates tools from an OpenAPI spec.
type GeneratorConfig ¶
GeneratorConfig configures the generator.
type Info ¶
type Info struct {
Title string `json:"title"`
Description string `json:"description,omitempty"`
Version string `json:"version"`
}
Info contains API metadata.
type JSONSchema ¶
type JSONSchema struct {
Type string `json:"type,omitempty"`
Description string `json:"description,omitempty"`
Properties map[string]JSONSchema `json:"properties,omitempty"`
Required []string `json:"required,omitempty"`
Items *JSONSchema `json:"items,omitempty"`
Enum []any `json:"enum,omitempty"`
Default any `json:"default,omitempty"`
}
JSONSchema represents a JSON Schema.
type MediaType ¶
type MediaType struct {
Schema *JSONSchema `json:"schema,omitempty"`
}
MediaType represents a media type.
type OpenAPISpec ¶
type OpenAPISpec struct {
OpenAPI string `json:"openapi"`
Info Info `json:"info"`
Servers []Server `json:"servers,omitempty"`
Paths map[string]PathItem `json:"paths"`
}
OpenAPISpec represents a parsed OpenAPI specification.
type Operation ¶
type Operation struct {
OperationID string `json:"operationId,omitempty"`
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Parameters []Parameter `json:"parameters,omitempty"`
RequestBody *RequestBody `json:"requestBody,omitempty"`
Responses Responses `json:"responses,omitempty"`
Tags []string `json:"tags,omitempty"`
}
Operation represents an API operation.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In string `json:"in"` // query, path, header, cookie
Description string `json:"description,omitempty"`
Required bool `json:"required,omitempty"`
Schema *JSONSchema `json:"schema,omitempty"`
}
Parameter represents an operation parameter.
type PathItem ¶
type PathItem struct {
Get *Operation `json:"get,omitempty"`
Post *Operation `json:"post,omitempty"`
Put *Operation `json:"put,omitempty"`
Delete *Operation `json:"delete,omitempty"`
Patch *Operation `json:"patch,omitempty"`
}
PathItem represents operations on a path.
type RequestBody ¶
type RequestBody struct {
Description string `json:"description,omitempty"`
Required bool `json:"required,omitempty"`
Content map[string]MediaType `json:"content,omitempty"`
}
RequestBody represents a request body.
type ResponseObj ¶
type ResponseObj struct {
Description string `json:"description,omitempty"`
Content map[string]MediaType `json:"content,omitempty"`
}
ResponseObj represents a response.
Source Files