Documentation
¶
Overview ¶
Package openapi assembles per-tool JSON Schemas from a dereferenced OpenAPI 3.1 document.
Input is the JSON of a dereferenced document (every $ref inlined, components.schemas retained). Parse decodes it once (returning ErrParse on bad JSON; it normalizes OpenAPI 3.0 nullable: true to a null-permitting type). The returned *Schemas then composes self-contained schemas: ParamsSchema / ParamSchema (optionally a named subset), BodySchema (application/json request body), Ref (named component), OutputObject / OutputItems / OutputValue (response wrappers), and Summary. Returned schemas are deep-cloned, so callers and the SDK may mutate them freely.
Only Parse returns an error. The composition methods instead panic (wrapping ErrUndefined) on an unknown name/path/operation/parameter — these are static, programmer-level mistakes, surfaced loudly rather than threaded through every call site.
Index ¶
- Variables
- func Int64StringSchema(description string) *jsonschema.Schema
- func Object(properties map[string]*jsonschema.Schema, required []string) *jsonschema.Schema
- func OutputValue(jsonType string) *jsonschema.Schema
- func StringifyIntParam(s *jsonschema.Schema, name string) *jsonschema.Schema
- type Int64String
- type Schemas
- func (s *Schemas) BodySchema(method, path string) *jsonschema.Schema
- func (s *Schemas) OutputItems(name string) *jsonschema.Schema
- func (s *Schemas) OutputObject(name string) *jsonschema.Schema
- func (s *Schemas) ParamSchema(method, path, name string) *jsonschema.Schema
- func (s *Schemas) ParamsSchema(method, path string, names ...string) *jsonschema.Schema
- func (s *Schemas) Ref(name string) *jsonschema.Schema
- func (s *Schemas) Summary(method, path string) string
Constants ¶
This section is empty.
Variables ¶
var ErrParse = errors.New("openapi parse")
ErrParse is wrapped with the decode error when Parse cannot decode the doc.
var ErrUndefined = errors.New("openapi undefined")
ErrUndefined is wrapped in the panic value for an unknown name/path/op/param.
Functions ¶
func Int64StringSchema ¶ added in v0.7.0
func Int64StringSchema(description string) *jsonschema.Schema
Int64StringSchema returns the input schema for an Int64String field: a string carrying a decimal integer, keeping the given description.
func Object ¶
func Object( properties map[string]*jsonschema.Schema, required []string, ) *jsonschema.Schema
Object assembles an object schema from properties and required field names.
func OutputValue ¶
func OutputValue(jsonType string) *jsonschema.Schema
OutputValue builds a scalar-response output schema, wrapped under "value".
func StringifyIntParam ¶ added in v0.7.0
func StringifyIntParam(s *jsonschema.Schema, name string) *jsonschema.Schema
StringifyIntParam rewrites the property named name in an assembled object schema to the Int64String form (string type + pattern), preserving that property's title and description; integer-only keywords (minimum, format, …) are dropped, as they no longer apply to a string. It returns s for chaining and panics (wrapping ErrUndefined) when name is absent — a missing property is a static wiring bug, matching the other openapi accessors. Use it to fix an OpenAPI-derived integer id param (e.g. from ParamsSchema) at the MCP boundary.
Types ¶
type Int64String ¶ added in v0.7.0
type Int64String int64
Int64String is an int64 that crosses a JSON/MCP boundary as a quoted decimal string, so 64-bit ids survive JavaScript clients (whose only number type is a float64, exact solely up to 2^53). Decoding is string-only: a bare JSON number is already truncated by such a client, so it is rejected rather than acted on. Pair the field with Int64StringSchema / StringifyIntParam so the advertised schema tells clients to send a string.
func (Int64String) Int64 ¶ added in v0.7.0
func (v Int64String) Int64() int64
Int64 returns the underlying value for passing to int64-typed APIs.
func (Int64String) MarshalJSON ¶ added in v0.7.0
func (v Int64String) MarshalJSON() ([]byte, error)
MarshalJSON emits the value as a quoted decimal string.
func (*Int64String) UnmarshalJSON ¶ added in v0.7.0
func (v *Int64String) UnmarshalJSON(data []byte) error
UnmarshalJSON accepts only a quoted decimal integer; a bare number, null, empty, or non-integer string is an error.
type Schemas ¶
type Schemas struct {
// contains filtered or unexported fields
}
Schemas assembles per-tool JSON Schemas from a parsed OpenAPI document.
func (*Schemas) BodySchema ¶
func (s *Schemas) BodySchema(method, path string) *jsonschema.Schema
BodySchema clones an op's application/json request-body schema; panics if the op is unknown or has no application/json request body.
func (*Schemas) OutputItems ¶
func (s *Schemas) OutputItems(name string) *jsonschema.Schema
OutputItems builds a slice-response output schema, wrapped under "items".
func (*Schemas) OutputObject ¶
func (s *Schemas) OutputObject(name string) *jsonschema.Schema
OutputObject builds an object-response output schema from the named component; panics if name is unknown or the component is not an object.
func (*Schemas) ParamSchema ¶
func (s *Schemas) ParamSchema(method, path, name string) *jsonschema.Schema
ParamSchema returns a single parameter's schema; panics if not found.
func (*Schemas) ParamsSchema ¶
func (s *Schemas) ParamsSchema( method, path string, names ...string, ) *jsonschema.Schema
ParamsSchema builds an input schema from an op's params (all, or a named subset); panics if the op is unknown or a requested name is not a param.
Source Files