Documentation
¶
Overview ¶
Package config describes the services pandorest imports and generates, the equivalent of Pandora's resource-manager.hcl. A repository that generates an SDK lists its services as Service values and hands them to pandorest.Run; paths are relative to the repository root, which is where its make targets run the command from.
Index ¶
Constants ¶
const DefaultDir = "api-defs"
DefaultDir is the directory a service's documents and definitions live in when its Dir is empty.
Variables ¶
This section is empty.
Functions ¶
func CompareVersions ¶
CompareVersions orders two version strings by their dot-separated parts, numerically where both parts are numbers (4.10 above 4.9), otherwise as text; a version with more parts is above its prefix.
Types ¶
type Naming ¶
type Naming string
Naming is how operations get their Go method names.
const ( // PathNaming builds names from the HTTP method and path, for documents // whose operationIds are machine-made and lossy (Emby's // getAudiocodecs, and duplicates). PathNaming Naming = "path" // OperationIDNaming uses the operationId (Jellyfin's are hand-written // and unique). OperationIDNaming Naming = "operationId" )
type Paging ¶
type Paging struct {
// Start and Limit are the query parameters: where to start and how many
// to answer. Start is the index of the first result wanted, from 0
// (Emby's StartIndex and Limit), unless ByPage says it is a page.
Start string
Limit string
// Items and Total are the properties of the answer: the page's results
// and how many there are in all (Emby's Items and TotalRecordCount).
Items string
Total string
// ByPage says Start is a page number, counted from 1, rather than an
// index: Sonarr's page and pageSize, answering records and
// totalRecords.
ByPage bool
}
Paging says how a service's list operations page, which is how the importer tells them from the rest and what the generator builds each one's Complete method on: a GET that takes both parameters and answers a model with both properties is a list. Names are matched without regard to case.
type Service ¶
type Service struct {
// Name is the -service flag and the prefix of the document and
// definitions names.
Name string
// Package is the Go package name of the generated SDK.
Package string
// Output is the generated package directory.
Output string
// Dir is the directory the documents and definitions are in; empty is
// DefaultDir.
Dir string
// Naming picks how method names are built.
Naming Naming
// TagSuffix is trimmed from tag names to make group names ("Service"
// on Emby: LibraryService is the Library group).
TagSuffix string
// PathPrefix is trimmed from a path before a method is named after it,
// so that every Sonarr operation is not named GetApiV3...: with /api/v3,
// GET /api/v3/series/{id} is GetSeriesById. A path outside the prefix is
// named in full, and the paths themselves keep it.
PathPrefix string
// Words spells the run-together words of the paths, which name methods
// with one capital otherwise: Sonarr's /api/v3/episodefile would make
// GetEpisodefile, and with "episodefile": "EpisodeFile" makes
// GetEpisodeFile. Keys are lower case and each value is its key's
// letters, or the import fails; a segment not listed is capitalised as
// it stands.
Words map[string]string
// ClientImport is the import path of the hand-written base client the
// generated package sends every request through.
ClientImport string
// Auth names how the service authenticates, and is recorded in its
// definitions. The client.go the generator writes by default wraps the
// token New is given in the base client's authorizer of this name,
// client.<Auth>(token).
Auth string
// Client, when set, is the Go source of client.go after its APIVersion
// constant, in place of the default: the Client type, a struct holding
// the base client in a field named Client, and New(baseURL, token
// string) (*Client, error), with whatever else the service's client
// declares (a hosted API's address, say). It refers to the base client
// as client and declares no imports: the generator writes them, for
// the packages generated code uses (errors, fmt, strings, strconv,
// net/http, net/url, io, encoding/json, context, slices), so a source
// that needs another does not compile. The generated tests hold New to
// refusing an empty token and a URL with no scheme, and to trimming a
// trailing slash.
Client string
// Notes is a paragraph added to the generated package's documentation,
// for what is true of the service's every operation and no document
// says: how it writes its dates, say.
Notes string
// Paging says how the service's lists page; nil is a service whose
// operations get no Complete method.
Paging *Paging
// PreferJSON reads a response that lists JSON beside another media type
// as JSON: Swashbuckle lists application/json, text/json and text/plain
// for every action ASP.NET's formatters can answer, and the text/plain
// there is the same JSON. Without it such a response is a file, which
// is what text/css listed beside JSON is on Jellyfin.
PreferJSON bool
// ExpectSameShape counts a status outside 2xx as one an operation
// expects when the document gives it the success answer's shape: a
// failure that still answers in full, as Sonarr's test-all answers 400
// with every provider's result when one of them fails. Without it only
// the 2xx statuses an operation declares are expected.
ExpectSameShape bool
// SendRequired holds the document to its word on required properties: a
// property a schema lists as required is always sent, an empty string
// as "" rather than not at all (Radarr refuses host settings saved
// without theirs). Without it required is not read.
SendRequired bool
// WrittenWhole names the object schemas callers read and write back
// whole - settings objects - whose empty strings and zero numbers the
// generated models send rather than leave out: the server reads a field
// left out as null, which is not the value that was read. A name the
// document does not have fails the import.
WrittenWhole []string
// KeepNull names the model fields, as Schema.property, whose null is
// not their zero, which the SDK holds as pointers where it holds every
// other number by value: season 0 is the specials and a parental limit
// of 0 is the strictest, so a season or a limit the server leaves out
// must not read as either. Each must be a number the document declares
// nullable, or the import fails naming it.
KeepNull []string
// Version, Spec and Definitions are set by Resolve: the document's
// version, the vendored OpenAPI document, and where the importer writes
// and the generator reads, the last two relative to the repository.
Version string
Spec string
Definitions string
// Root is the repository root the paths above are relative to; empty
// is the working directory.
Root string
}
Service is one server API.
Its document and definitions are versioned by the document's own version string: <dir>/<name>-openapi-<version>.json is imported into <dir>/<name>-<version>/ beside it, and Resolve picks the highest version present, which is the one the SDK is generated from. An older document can stay beside it for the diff, and a newer one is picked up by being added.
func Select ¶
Select returns the services named in a comma-separated list, or all of them for an empty one.
func (Service) DefinitionsPath ¶
DefinitionsPath is where one version's definitions are checked in.
func (Service) In ¶
In returns a copy of the service whose files are under root. The paths stay as configured, relative to the repository, because they are recorded in the definitions and the generated docs; Path resolves them.
func (Service) Resolve ¶
Resolve finds the service's documents under its directory and settles on the highest version: Spec is that document and Definitions its definitions directory. A service with no document is an error.