api

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

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

View Source
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.

View Source
const ExamplesDir = "examples"

ExamplesDir is the directory of the examples inside Examples.

Variables

View Source
var Examples embed.FS

Examples holds examples/<operationId>.json.

View Source
var Spec []byte

Spec is api/openapi.yaml.

Functions

func ExampleFile

func ExampleFile(operationID string) string

ExampleFile is the name of an operation's example inside Examples.

func IsJSON

func IsJSON(mediaType string) bool

IsJSON reports whether a media type is JSON (application/json or a +json suffix).

func Load

func Load(ctx context.Context) (*openapi3.T, error)

Load parses and validates the embedded spec.

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.

func (Frame) Encode

func (f Frame) Encode() ([]byte, error)

Encode writes the frame in the text/event-stream format, with its data on one line.

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

func Operations(doc *openapi3.T) ([]Operation, error)

Operations lists the spec's operations, sorted by path then method.

func (Operation) Example

func (o Operation) Example() ([]byte, error)

Example reads an operation's example file.

func (Operation) ExampleBody

func (o Operation) ExampleBody() ([]byte, error)

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

func (o Operation) ExampleFrames() ([]Frame, error)

ExampleFrames decodes an SSE example.

func (Operation) ExampleText

func (o Operation) ExampleText() (string, error)

ExampleText decodes the example of a non-JSON, non-SSE media type: the JSON string the file holds (for application/gzip, the uncompressed body).

func (Operation) HasBody

func (o Operation) HasBody() bool

HasBody reports whether the success response has a body, and so an example.

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).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL