forked from ebhomengo/niki
91 lines
3.9 KiB
Go
91 lines
3.9 KiB
Go
package spec
|
||
|
||
// Link represents a possible design-time link for a response.
|
||
// The presence of a link does not guarantee the caller’s ability to successfully invoke it,
|
||
// rather it provides a known relationship and traversal mechanism between responses and other operations.
|
||
// Unlike dynamic links (i.e. links provided in the response payload),
|
||
// the OAS linking mechanism does not require link information in the runtime response.
|
||
// For computing links, and providing instructions to execute them,
|
||
// a runtime expression is used for accessing values in an operation and using them as parameters while invoking the linked operation.
|
||
//
|
||
// https://spec.openapis.org/oas/v3.1.0#link-object
|
||
//
|
||
// Example:
|
||
//
|
||
// paths:
|
||
// /users/{id}:
|
||
// parameters:
|
||
// - name: id
|
||
// in: path
|
||
// required: true
|
||
// description: the user identifier, as userId
|
||
// schema:
|
||
// type: string
|
||
// get:
|
||
// responses:
|
||
// '200':
|
||
// description: the user being returned
|
||
// content:
|
||
// application/json:
|
||
// schema:
|
||
// type: object
|
||
// properties:
|
||
// uuid: # the unique user id
|
||
// type: string
|
||
// format: uuid
|
||
// links:
|
||
// address:
|
||
// # the target link operationId
|
||
// operationId: getUserAddress
|
||
// parameters:
|
||
// # get the `id` field from the request path parameter named `id`
|
||
// userId: $request.path.id
|
||
// # the path item of the linked operation
|
||
// /users/{userid}/address:
|
||
// parameters:
|
||
// - name: userid
|
||
// in: path
|
||
// required: true
|
||
// description: the user identifier, as userId
|
||
// schema:
|
||
// type: string
|
||
// # linked operation
|
||
// get:
|
||
// operationId: getUserAddress
|
||
// responses:
|
||
// '200':
|
||
// description: the user's address
|
||
type Link struct {
|
||
// A literal value or {expression} to use as a request body when calling the target operation.
|
||
RequestBody any `json:"requestBody,omitempty" yaml:"requestBody,omitempty"`
|
||
// A map representing parameters to pass to an operation as specified with operationId or identified via operationRef.
|
||
// The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and
|
||
// passed to the linked operation.
|
||
// The parameter name can be qualified using the parameter location [{in}.]{name} for operations that use
|
||
// the same parameter name in different locations (e.g. path.id).
|
||
Parameters map[string]any `json:"parameters,omitempty" yaml:"parameters,omitempty"`
|
||
// A server object to be used by the target operation.
|
||
Server *Extendable[Server] `json:"server,omitempty" yaml:"server,omitempty"`
|
||
// A relative or absolute URI reference to an OAS operation.
|
||
// This field is mutually exclusive of the operationId field, and MUST point to an Operation Object.
|
||
// Relative operationRef values MAY be used to locate an existing Operation Object in the OpenAPI definition.
|
||
// See the rules for resolving Relative References.
|
||
OperationRef string `json:"operationRef,omitempty" yaml:"operationRef,omitempty"`
|
||
// The name of an existing, resolvable OAS operation, as defined with a unique operationId.
|
||
// This field is mutually exclusive of the operationRef field.
|
||
OperationId string `json:"operationId,omitempty" yaml:"operationId,omitempty"`
|
||
// A description of the link.
|
||
// CommonMark syntax MAY be used for rich text representation.
|
||
Description string `json:"description,omitempty" yaml:"description,omitempty"`
|
||
}
|
||
|
||
// NewLinkSpec creates Link object.
|
||
func NewLinkSpec() *RefOrSpec[Extendable[Link]] {
|
||
return NewRefOrSpec[Extendable[Link]](nil, NewExtendable(&Link{}))
|
||
}
|
||
|
||
// NewLinkRef creates Ref object.
|
||
func NewLinkRef(ref *Ref) *RefOrSpec[Extendable[Link]] {
|
||
return NewRefOrSpec[Extendable[Link]](ref, nil)
|
||
}
|