Documentation
¶
Overview ¶
Package pandorest generates typed Go Services from vendored OpenAPI documents. It is inspired by Pandora, the go-azure-sdk generator (https://github.com/hashicorp/pandora), and keeps its pipeline, scaled down to a handful of documents in one repository:
import <dir>/<service>-openapi-<version>.json -> workarounds -> <dir>/<service>-<version>/*.json generate <dir>/<service>-<version> -> the service's package
A service's document and definitions are named by the document's version, and the highest version present is the one imported and generated from.
diff what a refreshed spec changes, against the checked-in definitions check the definitions match the spec and the package has every method resolve which document and definitions each service is at
A repository that generates an SDK keeps what is its own - the documents, the services they describe and the workarounds for their bugs - and a main of a few lines that hands them to this package:
func main() {
pandorest.Main(pandorest.Config{Services: services, Workarounds: workarounds})
}
which it runs from its root, as its make targets do:
go run ./sdk/pandorest import go run ./sdk/pandorest generate -service jellyfin go run ./sdk/pandorest diff go run ./sdk/pandorest diff -old api-defs/emby-4.9.0.30 -new api-defs/emby-4.10.0.40
The packages it writes send their requests through the client package, the base client they share. See the README for the design and how to refresh a spec.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrChanges = errors.New("the definitions differ")
ErrChanges is what diff -exit-code returns when there are changes.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// Services are the APIs, in the order the commands process them.
Services []config.Service
// Workarounds are the fixes for the bugs in the services' documents, in
// the order they are applied; each names the service it is for.
Workarounds []workarounds.Workaround
}
Config is what a repository generates its Services from.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package client is the base client every SDK pandorest generates sends its requests through, after go-azure-sdk's sdk/client: one copy in place of the one each repository used to keep.
|
Package client is the base client every SDK pandorest generates sends its requests through, after go-azure-sdk's sdk/client: one copy in place of the one each repository used to keep. |
|
Package config describes the services pandorest imports and generates, the equivalent of Pandora's resource-manager.hcl.
|
Package config describes the services pandorest imports and generates, the equivalent of Pandora's resource-manager.hcl. |
|
Package definitions is pandorest's normalised description of one server's API, the contract between the importer and the generator.
|
Package definitions is pandorest's normalised description of one server's API, the contract between the importer and the generator. |
|
Package differ reports what changed between two sets of definitions in API terms, after Pandora's data-api-differ: operations, options, bodies, models, fields and enum values added, removed or changed, with the changes that would break a caller of the generated SDK marked.
|
Package differ reports what changed between two sets of definitions in API terms, after Pandora's data-api-differ: operations, options, bodies, models, fields and enum values added, removed or changed, with the changes that would break a caller of the generated SDK marked. |
|
Package generator writes a Go SDK package from a service's definitions, the way Pandora's generator-go-sdk writes go-azure-sdk: it reads nothing but the definitions, and every decision it makes about the API was already made by the importer.
|
Package generator writes a Go SDK package from a service's definitions, the way Pandora's generator-go-sdk writes go-azure-sdk: it reads nothing but the definitions, and every decision it makes about the API was already made by the importer. |
|
Package importer turns a vendored OpenAPI document into definitions, the way Pandora's importer-rest-api-specs does for Azure: load the document, apply the named workarounds for its known bugs, then normalise it into the definitions model (Go names, types, status codes, paging, and which tag owns each model).
|
Package importer turns a vendored OpenAPI document into definitions, the way Pandora's importer-rest-api-specs does for Azure: load the document, apply the named workarounds for its known bugs, then normalise it into the definitions model (Go names, types, status codes, paging, and which tag owns each model). |
|
workarounds
Package workarounds is how a repository fixes the bugs in the OpenAPI documents it vendors, one named workaround per bug, after Pandora's dataworkarounds.
|
Package workarounds is how a repository fixes the bugs in the OpenAPI documents it vendors, one named workaround per bug, after Pandora's dataworkarounds. |
|
Package jsonrpc reads a server's own description of its JSON-RPC methods into the document the importer takes, so that a server with no OpenAPI document (TrueNAS, whose REST API is going) gets the same generated package as one with.
|
Package jsonrpc reads a server's own description of its JSON-RPC methods into the document the importer takes, so that a server with no OpenAPI document (TrueNAS, whose REST API is going) gets the same generated package as one with. |
|
Package openapi decodes the subset of an OpenAPI 3 document the importer reads.
|
Package openapi decodes the subset of an OpenAPI 3 document the importer reads. |
|
Package sweep is the read sweep a repository runs against a real server: every GET operation in a service's definitions, called on the generated SDK with arguments resolved from the suite's fixtures, and its answer decoded (or its file read).
|
Package sweep is the read sweep a repository runs against a real server: every GET operation in a service's definitions, called on the generated SDK with arguments resolved from the suite's fixtures, and its answer decoded (or its file read). |