Documentation
¶
Overview ¶
Package api holds the factory's HTTP contract: openapi.yaml and one example per operation's success response under examples/. Both are embedded, so factory-mock and the contract tests read the same files the code generators and the web app do: the files in this directory are the only copy.
An example is examples/<operationId>.json. Its content depends on the response's media type:
- a JSON media type (application/json, …+json): the body itself;
- text/event-stream: a JSON array of frames, {"event", "id", "data"};
- application/gzip: a JSON string holding the uncompressed body, gzip-compressed when served (the transcript, JSON Lines);
- any other media type (text/plain): a JSON string holding the body.
Operations whose success response has no body (204, 202 without content, 302) have no example file.
Index ¶
Constants ¶
const ( // MediaTypeSSE is the media type of server-sent events. MediaTypeSSE = "text/event-stream" // MediaTypeGzip is the media type of gzip-compressed bodies (transcripts). MediaTypeGzip = "application/gzip" )
Media types with their own example rules.
const ExamplesDir = "examples"
ExamplesDir is the directory of the examples inside Examples.
Variables ¶
var Examples embed.FS
Examples holds examples/<operationId>.json.
var Spec []byte
Spec is api/openapi.yaml.
Functions ¶
func ExampleFile ¶
ExampleFile is the name of an operation's example inside Examples.
Types ¶
type Frame ¶
type Frame struct {
Event string `json:"event"`
ID string `json:"id,omitzero"`
Data json.RawMessage `json:"data"`
}
Frame is one server-sent event of an SSE example.
type Operation ¶
type Operation struct {
ID string
Method string
// Path is the full path template: the effective server's path followed by the spec path,
// e.g. /api/v1/tasks/{id} or /hooks/{provider}.
Path string
Tags []string
// Status is the success status: the lowest 2xx response with a body, else the lowest 2xx
// response, else the lowest 3xx (the OAuth redirects).
Status int
// ContentType is the success response's media type; empty when it has no body.
ContentType string
// Media is the success response's media type object; nil when it has no body.
Media *openapi3.MediaType
// Operation is the spec's operation.
Operation *openapi3.Operation
}
Operation is one operation of the spec, flattened for routing and examples.
func Operations ¶
Operations lists the spec's operations, sorted by path then method.
func (Operation) ExampleBody ¶
ExampleBody renders a non-SSE example as the response body: the JSON itself for a JSON media type, the decoded string gzip-compressed for application/gzip, the decoded string otherwise. The output is deterministic.
func (Operation) ExampleFrames ¶
ExampleFrames decodes an SSE example.
func (Operation) ExampleText ¶
ExampleText decodes the example of a non-JSON, non-SSE media type: the JSON string the file holds (for application/gzip, the uncompressed body).
Directories
¶
| Path | Synopsis |
|---|---|
|
Command componentsgen writes the OpenAPI components of the v1alpha1 types into api/openapi.yaml, between its BEGIN GENERATED and END GENERATED markers (make generate).
|
Command componentsgen writes the OpenAPI components of the v1alpha1 types into api/openapi.yaml, between its BEGIN GENERATED and END GENERATED markers (make generate). |