Documentation
¶
Overview ¶
Package build turns an OpenAPI document into a cobra command tree.
Index ¶
Constants ¶
const ( InPath = "path" InQuery = "query" InHeader = "header" )
Parameter kinds, matching the spec's "in" values blip supports.
const ( TypeString = "string" TypeInteger = "integer" TypeNumber = "number" TypeBoolean = "boolean" TypeArray = "array" TypeObject = "object" )
Value types blip maps spec schemas onto.
const ( SourceSpec = "spec" SourceRoute = "route" )
Sources an operation can come from.
const JSONContentType = "application/json"
JSONContentType is the body type blip generates flags for.
const Legend = "name METHOD path args: bare=positional, ?query, @header, *=required, body:Schema"
Legend explains the compact notation. It is printed by describe, but never by describe --compact, which stays pure data.
const MaxReportedProblems = 3
MaxReportedProblems bounds a validation message. A body that is wrong in thirty places is wrong; listing all thirty helps nobody.
Variables ¶
var Reserved = map[string]bool{ "version": true, "init": true, "envs": true, "auth": true, "raw": true, "spec": true, "describe": true, "call": true, "help": true, "blip": true, }
Reserved names blip owns. A group that collides with one of these is renamed, because a spec must never be able to shadow blip's own commands.
Functions ¶
This section is empty.
Types ¶
type API ¶
type API struct {
Title string `json:"title"`
Version string `json:"version"`
Operations []*Operation `json:"operations"`
// Warnings are things the user should fix upstream, reported once.
Warnings []string `json:"-"`
}
API is a whole parsed document.
func Parse ¶
Parse turns a raw OpenAPI document into blip's model. Operations are visited in a fixed order, so a derived name never silently changes between runs.
func (*API) AddRoutes ¶
AddRoutes merges declared routes into the tree. A route with no group becomes a top-level command, which is what a config that names one is asking for.
func (*API) CompactLines ¶
CompactLines renders one dense line per operation. This is a contract an agent reads once at the start of a session, so the shape must stay stable:
<group> <name> <METHOD> <path> <params>
Path parameters appear bare, query parameters as ?name, headers as @name, a required parameter carries a trailing *, and a body as body:Schema or body!:Schema when required.
func (*API) DescribeLines ¶
DescribeLines renders the readable listing: grouped, with summaries.
type Body ¶
type Body struct {
Required bool `json:"required"`
ContentType string `json:"content_type"`
Schema string `json:"schema,omitempty"`
Flat bool `json:"flat"`
Fields []Field `json:"fields,omitempty"`
}
Body describes a request body. Only flat objects get --field; anything nested is --data only, deliberately.
type Field ¶
type Field struct {
Name string `json:"name"`
Type string `json:"type"`
Required bool `json:"required"`
Description string `json:"description,omitempty"`
Enum []string `json:"enum,omitempty"`
}
Field is one property of a flat request body.
type ListedOperation ¶
type ListedOperation struct {
*Operation
FullName string `json:"full_name"`
Command string `json:"command"`
}
ListedOperation is one operation as described.
type Listing ¶
type Listing struct {
Title string `json:"title"`
Version string `json:"version"`
Operations []ListedOperation `json:"operations"`
}
Listing is the JSON shape of describe --json, which adds the stable name that the model itself only computes.
type Operation ¶
type Operation struct {
ID string `json:"id,omitempty"`
Group string `json:"group"`
Name string `json:"name"`
Method string `json:"method"`
Path string `json:"path"`
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Deprecated bool `json:"deprecated,omitempty"`
Params []Param `json:"params,omitempty"`
Body *Body `json:"body,omitempty"`
// Derived is true when the spec gave no operationId and blip made a name up.
Derived bool `json:"derived"`
// Source says where the operation came from: the spec, or a [[route]] entry.
Source string `json:"source"`
// contains filtered or unexported fields
}
Operation is one callable endpoint.
func (*Operation) FullName ¶
FullName is the stable address of an operation: its operationId when it has one, otherwise group and name joined.
func (*Operation) PathParams ¶
PathParams returns the path parameters in the order they appear in the path.
func (*Operation) ValidateResponse ¶
ValidateResponse checks a response body against the schema the spec declares for that status. It reports nil when the spec says nothing about the status, which is the common case and not a problem.
type Param ¶
type Param struct {
Name string `json:"name"`
In string `json:"in"`
Required bool `json:"required"`
Description string `json:"description,omitempty"`
Type string `json:"type"`
ItemType string `json:"item_type,omitempty"`
Enum []string `json:"enum,omitempty"`
Default string `json:"default,omitempty"`
}
Param is one path, query or header parameter.
Source Files