Documentation
¶
Overview ¶
Package workarounds is how a repository fixes the bugs in the OpenAPI documents it vendors, one named workaround per bug, after Pandora's dataworkarounds. The workarounds themselves live with the documents, in the repository that vendors them; this package is the interface they implement, the helpers they share, and the test every one of them must pass (Verify).
Every workaround patches the loaded document before it is normalised, and every one first checks that the bug it fixes is still there: when the document no longer has the problem (a refreshed spec declares the missing parameter, the duplicate operationId is gone) the workaround fails the import instead of silently doing nothing, so dead workarounds get deleted rather than accumulating. The applied names are recorded in the service's definitions.
Only the shape of the document belongs in a workaround: what an operation takes and answers. Behaviour the document cannot express (Emby keying watch state by provider id, a filter it silently drops) stays in the hand-written code over the generated SDK, next to the live tests that found it.
Index ¶
- func AddParameters(spec *openapi.Spec, targets []string, params ...Param) error
- func Apply(all []Workaround, service string, spec *openapi.Spec, log func(string)) ([]string, error)
- func JSONResponse(op *openapi.Operation, what string) (*openapi.MediaType, error)
- func Operation(spec *openapi.Spec, method, path string) (*openapi.Operation, error)
- func Property(spec *openapi.Spec, schema, name string) (*openapi.Schema, error)
- func Verify(all []Workaround, load func(service string) (*openapi.Spec, error)) error
- type Param
- type Workaround
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddParameters ¶
AddParameters adds undeclared parameters to operations, each target a method and a path ("GET /Items"), failing when any target already declares one of them.
func Apply ¶
func Apply(all []Workaround, service string, spec *openapi.Spec, log func(string)) ([]string, error)
Apply runs every workaround in all that is for a service, in order, logging each, and returns the names applied.
func JSONResponse ¶
JSONResponse is an operation's 200 application/json media type, or the error a workaround returns when the document no longer declares one, rather than a nil pointer where a message is promised. what names the operation in that error.
func Verify ¶
Verify is the test a repository's workarounds must pass, against the documents it vendors: load reads a fresh copy of a service's document. No two workarounds share a name; each is named for its service and says what bug it fixes; the bug is in the document; applying it to the document it already fixed fails, the cheapest stand-in for a document fixed upstream, so it would notice the bug being gone; and on a document that has lost the 200 responses it reads it returns rather than panics. Every problem found is in the error, one to a line.
Types ¶
type Param ¶
Param is a parameter a workaround adds: In is openapi.InQuery, InHeader or InPath, and Type one of the openapi types. A header named Accept is how a caller is given the say over what one call asks for, for a server that chooses its answer by it: the option, when set, is the whole header.
type Workaround ¶
type Workaround interface {
// Name identifies the workaround in logs and in Service.json; it starts
// with its service's name and a dash.
Name() string
// Service is the config service name it applies to.
Service() string
// Bug says what is wrong with the document and how the server behaves.
Bug() string
// Apply patches the document, or returns an error when the bug it fixes
// is not there (fixed upstream, or the operation is gone).
Apply(spec *openapi.Spec) error
}
Workaround fixes one bug in one service's document.