definitions

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: GPL-3.0 Imports: 8 Imported by: 0

Documentation

Overview

Package definitions is pandorest's normalised description of one server's API, the contract between the importer and the generator. The importer writes it from an OpenAPI document (after the workarounds have patched the document); the generator reads only this, never the document. It is checked in under api-defs/<service>-<version>/, one JSON file per spec tag plus Service.json, so a spec refresh shows up as a readable diff and the differ can report what changed in API terms.

Everything the generator needs is decided here rather than in the generator: Go names, Go-facing types, expected status codes, which operations page, and which tag owns each model.

Index

Constants

View Source
const (
	InQuery  = "Query"
	InHeader = "Header"
)

Option locations.

View Source
const CommonGroup = "Common"

CommonGroup owns the models and constants that more than one tag's operations use (or none do).

View Source
const ServiceFile = "Service.json"

ServiceFile is the service description inside a definitions directory; every other JSON file there is one group.

Variables

This section is empty.

Functions

func Marshal

func Marshal(v any) ([]byte, error)

Marshal renders a value the way the definition files hold it: indented, without HTML escaping (descriptions carry < and &), with a final newline.

func Save

func Save(svc *Service, dir string) error

Save writes a definitions directory, removing group files that no longer have a group so a tag that disappears from the document disappears here.

func Validate

func Validate(svc *Service) error

Validate checks a service's definitions are self-consistent: every reference resolves, and no two operations share a name or a method and path. The importer runs it on what it produces and the generator on what it reads, so hand-edited definitions fail before any code is written.

Types

type Body

type Body struct {
	// ContentType is the media type sent or expected. A wildcard such as
	// image/* means the caller names the concrete type.
	ContentType string `json:"ContentType"`
	// Type is RawFile for bodies that are not JSON.
	Type TypeRef `json:"Type"`
}

Body is a request or response body.

type Constant

type Constant struct {
	Name        string          `json:"Name"`
	SchemaName  string          `json:"SchemaName"`
	Description string          `json:"Description,omitempty"`
	Values      []ConstantValue `json:"Values"`
}

Constant is a string enum.

type ConstantValue

type ConstantValue struct {
	// Name is the Go constant name.
	Name  string `json:"Name"`
	Value string `json:"Value"`
}

ConstantValue is one member of an enum.

type Field

type Field struct {
	Name        string  `json:"Name"`
	JSONName    string  `json:"JsonName"`
	Description string  `json:"Description,omitempty"`
	Type        TypeRef `json:"Type"`
	Nullable    bool    `json:"Nullable,omitempty"`
	// Required is set when the document says an object must carry the
	// property, for a service whose config holds it to that (SendRequired):
	// the generated field is then always sent, its zero included.
	Required bool `json:"Required,omitempty"`
	// KeepsNull makes the generated field a pointer, so the document's null
	// is told from the number's zero: the fields the service config names
	// in KeepNull. Every other number is held by value.
	KeepsNull bool `json:"KeepsNull,omitempty"`
}

Field is one property of a model.

type Group

type Group struct {
	// Name is the Go-facing name used in file names, e.g. "LibraryStructure".
	Name string `json:"Name"`
	// Tag is the tag as the document spells it, e.g. "LibraryStructureService";
	// empty for the common group.
	Tag        string      `json:"Tag,omitempty"`
	Operations []Operation `json:"Operations,omitempty"`
	Models     []Model     `json:"Models,omitempty"`
	Constants  []Constant  `json:"Constants,omitempty"`
}

Group is one spec tag: its operations, and the models and constants no other tag uses.

type Model

type Model struct {
	Name string `json:"Name"`
	// SchemaName is the component schema; empty for an object declared
	// inline in another model's property.
	SchemaName  string  `json:"SchemaName,omitempty"`
	Description string  `json:"Description,omitempty"`
	Fields      []Field `json:"Fields,omitempty"`
	// Union lists the variants when the schema is a oneOf/anyOf; such a
	// model has no fields and is raw JSON for the caller to decode.
	Union []string `json:"Union,omitempty"`
	// WrittenWhole marks a model callers read and write back whole - a
	// settings object - so its empty strings and zero numbers are sent
	// rather than left out: the server reads a field left out as null,
	// which is not the value that was read, and not a value it will save.
	WrittenWhole bool `json:"WrittenWhole,omitempty"`
}

Model is an object schema, or a oneOf/anyOf union kept as raw JSON.

type ObjectType

type ObjectType string

ObjectType is the kind of a TypeRef.

const (
	Boolean    ObjectType = "Boolean"
	Integer    ObjectType = "Integer"
	Integer64  ObjectType = "Integer64"
	Float      ObjectType = "Float"
	Double     ObjectType = "Double"
	String     ObjectType = "String"
	List       ObjectType = "List"
	Dictionary ObjectType = "Dictionary"
	Reference  ObjectType = "Reference"
	RawObject  ObjectType = "RawObject"
	Any        ObjectType = "Any"
	RawFile    ObjectType = "RawFile"
)

The object types. Integer is a 32-bit integer (Go int), Integer64 a 64-bit one; Float is float32 and Double float64. RawObject is JSON the caller decodes (untyped objects, unions, binary strings); Any is a value of no declared type; RawFile is a body that is not JSON.

type Operation

type Operation struct {
	// Name is the Go method name.
	Name        string `json:"Name"`
	OperationID string `json:"OperationId,omitempty"`
	Method      string `json:"Method"`
	// Path is the document's path template, e.g. /Items/{Id}/Similar.
	Path        string `json:"Path"`
	Description string `json:"Description,omitempty"`
	Deprecated  bool   `json:"Deprecated,omitempty"`
	// PathParameters are the template placeholders in path order.
	PathParameters []PathParameter `json:"PathParameters,omitempty"`
	// Options are the query and header parameters, the options struct.
	Options []Option `json:"Options,omitempty"`
	// Request is the request body; nil when the operation takes none.
	Request *Body `json:"Request,omitempty"`
	// Response is the success response body; nil when there is none.
	Response            *Body `json:"Response,omitempty"`
	ExpectedStatusCodes []int `json:"ExpectedStatusCodes"`
	// Pageable is set for the list operations, which also get a Complete
	// method that pages through every result.
	Pageable *Pageable `json:"Pageable,omitempty"`
}

Operation is one HTTP method on one path, and one method on the client.

func (*Operation) Key

func (o *Operation) Key() string

Key identifies an operation independently of its Go name.

func (*Operation) Types

func (o *Operation) Types() []TypeRef

Types lists every type an operation mentions directly.

type Option

type Option struct {
	// Name is the parameter as sent.
	Name string `json:"Name"`
	// Field is the Go field name.
	Field       string `json:"Field"`
	In          string `json:"In"`
	Description string `json:"Description,omitempty"`
	Deprecated  bool   `json:"Deprecated,omitempty"`
	// Required is set when the document says the operation needs the option.
	Required bool    `json:"Required,omitempty"`
	Type     TypeRef `json:"Type"`
	// CommaSeparated sends a List as one comma-separated value; otherwise
	// each element is sent under the parameter's name.
	CommaSeparated bool `json:"CommaSeparated,omitempty"`
	// DeepObject sends a Dictionary as one parameter per key, name[key]=value
	// (OpenAPI's deepObject style, which Jellyfin's stream options use);
	// otherwise the dictionary goes as one JSON string.
	DeepObject bool `json:"DeepObject,omitempty"`
}

Option is one query or header parameter, a field of the options struct.

type Pageable

type Pageable struct {
	// StartIndexOption and LimitOption are the options fields: where a page
	// starts and how many results it holds.
	StartIndexOption string `json:"StartIndexOption"`
	LimitOption      string `json:"LimitOption"`
	// ByPage is set when the list pages by page number: StartIndexOption is
	// then the page wanted, counted from 1, rather than the index of its
	// first result.
	ByPage bool `json:"ByPage,omitempty"`
	// ItemsField and TotalField are fields of the response model.
	ItemsField string  `json:"ItemsField"`
	TotalField string  `json:"TotalField"`
	ItemType   TypeRef `json:"ItemType"`
}

Pageable says how a list operation pages.

type PathParameter

type PathParameter struct {
	// Name is the placeholder as the template spells it.
	Name string `json:"Name"`
	// Argument is the Go argument name.
	Argument string  `json:"Argument"`
	Type     TypeRef `json:"Type"`
}

PathParameter is a placeholder of the path template.

type Service

type Service struct {
	// Name is the service's name in the pandorest config and the
	// prefix of its api-defs directory, e.g. "emby" for emby-4.10.0.40.
	Name string `json:"Name"`
	// Package is the Go package the generator writes, e.g. "emby".
	Package string `json:"Package"`
	// Title and APIVersion are the document's info block.
	Title      string `json:"Title"`
	APIVersion string `json:"ApiVersion"`
	// Source is the document the definitions were imported from.
	Source string `json:"Source"`
	// Auth names how the service authenticates: the base client's
	// authorizer the default client.go wraps New's token in.
	Auth string `json:"Auth"`
	// Workarounds lists the importer workarounds applied, in order.
	Workarounds []string `json:"Workarounds"`

	Groups []Group `json:"-"`
}

Service describes one server's API. It is Service.json; the groups are the per-tag files next to it.

func Load

func Load(dir string) (*Service, error)

Load reads a definitions directory.

func (*Service) Constants

func (s *Service) Constants() map[string]*Constant

Constants returns every constant of the service by name.

func (*Service) Models

func (s *Service) Models() map[string]*Model

Models returns every model of the service by name.

func (*Service) Operations

func (s *Service) Operations() []*Operation

Operations returns every operation of the service.

type TypeRef

type TypeRef struct {
	Type ObjectType `json:"Type"`
	// ReferenceName names the model or constant of a Reference.
	ReferenceName string `json:"ReferenceName,omitempty"`
	// NestedItem is the element type of a List or Dictionary.
	NestedItem *TypeRef `json:"NestedItem,omitempty"`
}

TypeRef is the type of a field, parameter or body.

func (TypeRef) Equal

func (t TypeRef) Equal(o TypeRef) bool

Equal reports whether two types are the same.

func (TypeRef) Numeric

func (t TypeRef) Numeric() bool

Numeric reports whether the type is a number: an integer or a float of either size.

func (TypeRef) String

func (t TypeRef) String() string

String renders a type for logs and diffs: List[Reference(BaseItemDto)].

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL