Documentation
¶
Overview ¶
Package openapi declares the registration types (Service and Endpoint) that describe a microservice's externally-visible features, along with Render which converts a Service into an OpenAPI 3.1 Document.
Index ¶
Constants ¶
const ( // FeatureFunction is a typed request/response endpoint (RPC). FeatureFunction = "function" // FeatureWeb is a raw HTTP handler endpoint. FeatureWeb = "web" // FeatureWorkflow is a workflow graph endpoint. FeatureWorkflow = "workflow" // FeatureTask is a workflow task endpoint. FeatureTask = "task" // FeatureOutboundEvent is an event published by the microservice. Its route is // what subscribers bind their inbound handlers to. Outbound events are not // rendered in the OpenAPI doc and are not exposed as LLM tools. FeatureOutboundEvent = "outboundevent" )
The feature type constants identify the kind of a Microbus endpoint. They are assigned to [Endpoint.Type].
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Components ¶ added in v1.26.0
type Components struct {
Schemas map[string]*jsonschema.Schema `json:"schemas,omitzero"`
SecuritySchemes map[string]*SecurityScheme `json:"securitySchemes,omitzero"`
}
Components holds a set of reusable objects for different aspects of the OpenAPI schema. https://spec.openapis.org/oas/v3.1.0#components-object
type Document ¶ added in v1.27.0
type Document struct {
OpenAPI string `json:"openapi"`
Info Info `json:"info"`
Servers []*Server `json:"servers,omitzero"`
Paths map[string]map[string]*Operation `json:"paths,omitzero"`
Components *Components `json:"components,omitzero"`
Tags []*Tag `json:"tags,omitzero"`
}
Document is the root object of the OpenAPI document. https://spec.openapis.org/oas/v3.1.0#openapi-object
func Render ¶ added in v1.27.0
Render builds an OpenAPI 3.1 Document from a service registration. All schema names (component keys and $ref pointers) are prefixed with the service hostname, with dots converted to underscores. The prefix scopes schemas to their owning service so multiple services' docs can be aggregated without component-key collisions.
type Endpoint ¶
type Endpoint struct {
Hostname string
Type string
Name string
Method string
Route string
Summary string
Description string
InputArgs any
OutputArgs any
RequiredClaims string
}
Endpoint describes a single endpoint of a microservice, such as an RPC function.
func (*Endpoint) Port ¶ added in v1.27.0
Port returns the port that the endpoint listens on, as a string. The default is "443".
The port is parsed from the [Route] in any of these forms:
- ":NNN" or ":NNN/path" - the explicit port prefix
- "//host:NNN/path" - a protocol-relative absolute route
- "https://host:NNN/path" or "http://host:NNN/path" - a full URL
- any other form (including "/path", "//host/path", or empty) - defaults to "443" ("80" for an "http://" URL with no port)
type Info ¶ added in v1.26.0
type Info struct {
Title string `json:"title"`
Description string `json:"description,omitzero"`
Version string `json:"version,omitzero"`
}
Info provides metadata about the API. https://spec.openapis.org/oas/v3.1.0#info-object
type MediaType ¶ added in v1.26.0
type MediaType struct {
Description string `json:"description,omitzero"`
Schema *jsonschema.Schema `json:"schema,omitzero"`
}
MediaType provides schema and examples for the media type identified by its key. https://spec.openapis.org/oas/v3.1.0#media-type-object
type Operation ¶ added in v1.26.0
type Operation struct {
Summary string `json:"summary"`
Description string `json:"description,omitzero"`
XFeatureType string `json:"x-feature-type,omitzero"`
XName string `json:"x-name,omitzero"`
Tags []string `json:"tags,omitzero"`
Parameters []*Parameter `json:"parameters,omitzero"`
RequestBody *RequestBody `json:"requestBody,omitzero"`
Responses map[string]*Response `json:"responses,omitzero"`
Security []*SecurityRequirement `json:"security,omitzero"`
}
Operation describes a single API operation on a path. https://spec.openapis.org/oas/v3.1.0#operation-object
type Parameter ¶ added in v1.26.0
type Parameter struct {
Name string `json:"name"`
In string `json:"in"`
Description string `json:"description,omitzero"`
Schema *jsonschema.Schema `json:"schema,omitzero"`
Style string `json:"style,omitzero"`
Explode bool `json:"explode,omitzero"`
Required bool `json:"required,omitzero"`
}
Parameter describes a single operation parameter. https://spec.openapis.org/oas/v3.1.0#parameter-object
type RequestBody ¶ added in v1.26.0
type RequestBody struct {
Description string `json:"description,omitzero"`
Required bool `json:"required,omitzero"`
Content map[string]*MediaType `json:"content,omitzero"`
}
RequestBody describes a single request body. https://spec.openapis.org/oas/v3.1.0#request-body-object
type Response ¶ added in v1.26.0
type Response struct {
Description string `json:"description,omitzero"`
Content map[string]*MediaType `json:"content,omitzero"`
}
Response describes a single response from an API Operation. https://spec.openapis.org/oas/v3.1.0#response-object
type SecurityRequirement ¶ added in v1.26.0
SecurityRequirement specifies a security scheme required to access an API Operation. https://spec.openapis.org/oas/v3.1.0#security-requirement-object
type SecurityScheme ¶ added in v1.26.0
type SecurityScheme struct {
Type string `json:"type,omitzero"`
Description string `json:"description,omitzero"`
Scheme string `json:"scheme,omitzero"`
BearerFormat string `json:"bearerFormat,omitzero"`
}
SecurityScheme describes means of authentication. https://spec.openapis.org/oas/v3.1.0#security-scheme-object
type Server ¶ added in v1.26.0
Server represents a server. https://spec.openapis.org/oas/v3.1.0#server-object
type Service ¶
type Service struct {
ServiceName string
Description string
Version int
Endpoints []*Endpoint
RemoteURI string
}
Service describes the externally-visible features of a microservice. The [Endpoints] should be treated as immutable after registration.
type Tag ¶ added in v1.27.0
Tag groups a set of operations under a label, typically rendered as a collapsible section by OpenAPI tooling. The aggregator at the portal uses one tag per source service. https://spec.openapis.org/oas/v3.1.0#tag-object
Source Files