Documentation ¶
Overview ¶
package arazzo provides an API for working with Arazzo documents including reading, creating, mutating, walking and validating them.
The Arazzo Specification is a mechanism for orchestrating API calls, defining their sequences and dependencies, to achieve specific outcomes when working with API descriptions like OpenAPI.
Example (Creating) ¶
package main import ( "bytes" "context" "fmt" "github.com/speakeasy-api/openapi/arazzo" "github.com/speakeasy-api/openapi/pointer" ) func main() { ctx := context.Background() arazzo := &arazzo.Arazzo{ Arazzo: arazzo.Version, Info: arazzo.Info{ Title: "My Workflow", Summary: pointer.From("A summary"), Version: "1.0.0", }, // ... } buf := bytes.NewBuffer([]byte{}) err := arazzo.Marshal(ctx, buf) if err != nil { panic(err) } fmt.Printf("%s", buf.String()) }
Output:
Example (Mutating) ¶
package main import ( "bytes" "context" "fmt" "os" "github.com/speakeasy-api/openapi/arazzo" ) func main() { ctx := context.Background() f, err := os.Open("arazzo.yaml") if err != nil { panic(err) } arazzo, _, err := arazzo.Unmarshal(ctx, f) if err != nil { panic(err) } arazzo.Info.Title = "My updated workflow title" buf := bytes.NewBuffer([]byte{}) if err := arazzo.Marshal(ctx, buf); err != nil { panic(err) } fmt.Printf("%s", buf.String()) }
Output:
Example (ReadAndMutate) ¶
The below examples should be copied into the README.md file if every changed TODO: automate this
package main import ( "bytes" "context" "fmt" "os" "github.com/speakeasy-api/openapi/arazzo" ) func main() { ctx := context.Background() r, err := os.Open("testdata/speakeasybar.arazzo.yaml") if err != nil { panic(err) } defer r.Close() // Unmarshal the Arazzo document which will also validate it against the Arazzo Specification a, validationErrs, err := arazzo.Unmarshal(ctx, r) if err != nil { panic(err) } // Validation errors are returned separately from any errors that block the document from being unmarshalled // allowing an invalid document to be mutated and fixed before being marshalled again for _, err := range validationErrs { fmt.Println(err.Error()) } // Mutate the document by just modifying the returned Arazzo object a.Info.Title = "Speakeasy Bar Workflows" buf := bytes.NewBuffer([]byte{}) // Marshal the document to a writer if err := arazzo.Marshal(ctx, a, buf); err != nil { panic(err) } fmt.Println(buf.String()) }
Output:
Example (Validating) ¶
package main import ( "context" "fmt" "os" "github.com/speakeasy-api/openapi/arazzo" ) func main() { ctx := context.Background() f, err := os.Open("arazzo.yaml") if err != nil { panic(err) } _, validationErrs, err := arazzo.Unmarshal(ctx, f) if err != nil { panic(err) } for _, err := range validationErrs { fmt.Printf("%s\n", err.Error()) } }
Output:
Example (Walking) ¶
package main import ( "context" "fmt" "os" "github.com/speakeasy-api/openapi/arazzo" ) func main() { ctx := context.Background() f, err := os.Open("arazzo.yaml") if err != nil { panic(err) } a, _, err := arazzo.Unmarshal(ctx, f) if err != nil { panic(err) } err = arazzo.Walk(ctx, a, func(ctx context.Context, node, parent arazzo.MatchFunc, a *arazzo.Arazzo) error { return node(arazzo.Matcher{ Workflow: func(workflow *arazzo.Workflow) error { fmt.Printf("Workflow: %s\n", workflow.WorkflowID) return nil }, }) }) if err != nil { panic(err) } }
Output:
Index ¶
- Constants
- func GetValueOrExpressionValue(value ValueOrExpression) (*yaml.Node, *expression.Expression, error)
- func Marshal(ctx context.Context, arazzo *Arazzo, w io.Writer) error
- func Walk(ctx context.Context, arazzo *Arazzo, visit VisitFunc) error
- type Arazzo
- type Components
- type FailureAction
- type FailureActionType
- type In
- type Info
- type MatchFunc
- type Matcher
- type Option
- type Outputs
- type Parameter
- type PayloadReplacement
- type RequestBody
- type Reusable
- type ReusableFailureAction
- type ReusableParameter
- type ReusableSuccessAction
- type SourceDescription
- type SourceDescriptionType
- type SourceDescriptions
- type Step
- type Steps
- type SuccessAction
- type SuccessActionType
- type Value
- type ValueOrExpression
- type VisitFunc
- type Workflow
- type Workflows
Examples ¶
Constants ¶
const ( // SourceDescriptionTypeOpenAPI represents a SourceDescription that describes an OpenAPI document. SourceDescriptionTypeOpenAPI = "openapi" // SourceDescriptionTypeArazzo represents a SourceDescription that describes an Arazzo document. SourceDescriptionTypeArazzo = "arazzo" )
const ( // ErrTerminate is a sentinel error that can be returned from a Walk function to terminate the walk. ErrTerminate = errors.Error("terminate") )
const Version = "1.0.0"
Version is the version of the Arazzo Specification that this package conforms to.
Variables ¶
This section is empty.
Functions ¶
func GetValueOrExpressionValue ¶
func GetValueOrExpressionValue(value ValueOrExpression) (*yaml.Node, *expression.Expression, error)
GetValueOrExpressionValue will return the value or expression from the provided ValueOrExpression.
Types ¶
type Arazzo ¶
type Arazzo struct { // Arazzo is the version of the Arazzo Specification that this document conforms to. Arazzo string // Info provides metadata about the Arazzo document. Info Info // SourceDescriptions provides a list of SourceDescription objects that describe the source of the data that the workflow is orchestrating. SourceDescriptions SourceDescriptions // Workflows provides a list of Workflow objects that describe the orchestration of API calls. Workflows Workflows // Components provides a list of reusable components that can be used in the workflow. Components *Components // Extensions provides a list of extensions to the Arazzo document. Extensions *extensions.Extensions // contains filtered or unexported fields }
Arazzo is the root object for an Arazzo document.
func Unmarshal ¶
func Unmarshal(ctx context.Context, doc io.Reader, opts ...Option[unmarshalOptions]) (*Arazzo, []error, error)
Unmarshal will unmarshal and validate an Arazzo document from the provided io.Reader. Validation can be skipped by using arazzo.WithSkipValidation() as one of the options when calling this function.
func (*Arazzo) GetCore ¶
GetCore will return the low level representation of the Arazzo document. Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
type Components ¶
type Components struct { // Inputs provides a list of reusable JSON Schemas that can be referenced from inputs and other JSON Schemas. Inputs *sequencedmap.Map[string, oas31.JSONSchema] // Parameters provides a list of reusable parameters that can be referenced from workflows and steps. Parameters *sequencedmap.Map[string, Parameter] // SuccessActions provides a list of reusable success actions that can be referenced from workflows and steps. SuccessActions *sequencedmap.Map[string, SuccessAction] // FailureActions provides a list of reusable failure actions that can be referenced from workflows and steps. FailureActions *sequencedmap.Map[string, FailureAction] // Extensions provides a list of extensions to the Components object. Extensions *extensions.Extensions // contains filtered or unexported fields }
Components holds reusable components that can be referenced in an Arazzo document.
func (*Components) GetCore ¶
func (c *Components) GetCore() *core.Components
GetCore will return the low level representation of the components object. Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
func (*Components) Validate ¶
func (c *Components) Validate(ctx context.Context, opts ...validation.Option) []error
Validate validates the Components object.
type FailureAction ¶
type FailureAction struct { // Name is the case sensitive name of the failure action. Name string // Type is the type of action to take on failure. Type FailureActionType // WorkflowID is the workflow ID of the workflow/step to go to on failure. Mutually exclusive to StepID. WorkflowID *expression.Expression // StepID is the step ID of the workflow/step to go to on failure. Mutually exclusive to WorkflowID. StepID *string // RetryAfter is the number of seconds to wait before retrying the workflow/step on failure. RetryAfter *float64 // RetryLimit is the number of times to retry the workflow/step on failure. If not set a single retry will be attempted if type is retry. RetryLimit *int // A list of assertions to check before taking the action. Criteria []criterion.Criterion // Extensions provides a list of extensions to the FailureAction object. Extensions *extensions.Extensions // contains filtered or unexported fields }
FailureAction represents an action to take on failure of a workflow/step.
func (*FailureAction) GetCore ¶
func (f *FailureAction) GetCore() *core.FailureAction
GetCore will return the low level representation of the failure action object. Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
func (FailureAction) Validate ¶
func (f FailureAction) Validate(ctx context.Context, opts ...validation.Option) []error
Validate will validate the failure action object. Requires an Arazzo object to be passed via validation options with validation.WithContextObject(). If a Workflow object is provided via validation options with validation.WithContextObject() then the FailureAction will be validated with the context of the workflow.
type FailureActionType ¶
type FailureActionType string
FailureActionType represents the type of action to take on failure.
const ( // FailureActionTypeEnd indicates that the workflow/step should end. FailureActionTypeEnd FailureActionType = "end" // FailureActionTypeGoto indicates that the workflow/step should go to another workflow/step on failure. FailureActionTypeGoto FailureActionType = "goto" // FailureActionTypeRetry indicates that the workflow/step should retry on failure. FailureActionTypeRetry FailureActionType = "retry" )
type In ¶
type In string
In represents the location of a parameter.
const ( // InPath indicates that the parameter is in the path of the request. InPath In = "path" // InQuery indicates that the parameter is in the query of the request. InQuery In = "query" // InHeader indicates that the parameter is in the header of the request. InHeader In = "header" // InCookie indicates that the parameter is in the cookie of the request. InCookie In = "cookie" // InBody indicates that the parameter is in the body of the request. InBody In = "body" )
type Info ¶
type Info struct { // Title is the name of the Arazzo document Title string // Summary is a short description of the Arazzo document Summary *string // Description is a longer description of the Arazzo document. May contain CommonMark syntax. Description *string // Version is the version of the Arazzo document Version string // Extensions provides a list of extensions to the Info object. Extensions *extensions.Extensions // contains filtered or unexported fields }
Info represents metadata about the Arazzo document
type MatchFunc ¶
MatchFunc represents a particular node in the Arazzo document that can be matched. Pass it a Matcher with the appropriate functions to populated to match the node type you are interested in.
type Matcher ¶
type Matcher struct { Arazzo func(*Arazzo) error Info func(*Info) error SourceDescription func(*SourceDescription) error Workflow func(*Workflow) error ReusableParameter func(ReusableParameter) error JSONSchema func(oas31.JSONSchema) error Step func(*Step) error ReusableSuccessAction func(ReusableSuccessAction) error ReusableFailureAction func(ReusableFailureAction) error Components func(*Components) error Parameter func(*Parameter) error SuccessAction func(*SuccessAction) error FailureAction func(*FailureAction) error }
Matcher is a struct that can be used to match specific nodes in the Arazzo document.
type Option ¶
type Option[T any] func(o *T)
func WithSkipValidation ¶
func WithSkipValidation() Option[unmarshalOptions]
WithSkipValidation will skip validation of the Arazzo document during unmarshalling. Useful to quickly load a document that will be mutated and validated later.
type Outputs ¶
type Outputs = *sequencedmap.Map[string, expression.Expression]
Outputs is a map of friendly name to expressions that extract data from the workflows/steps.
type Parameter ¶
type Parameter struct { // Name is the case sensitive name of the parameter. Name string // In is the location of the parameter within an operation. In *In // Value represents either the static value of the parameter or an expression that will be evaluated to produce the value. Value ValueOrExpression // Extensions provides a list of extensions to the Parameter object. Extensions *extensions.Extensions // contains filtered or unexported fields }
Parameter represents parameters that will be passed to a workflow or operation referenced by a step.
func (*Parameter) GetCore ¶
GetCore will return the low level representation of the parameter object. Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
type PayloadReplacement ¶
type PayloadReplacement struct { // Target is a JSON pointer of XPath expression to the value to be replaced. Target jsonpointer.JSONPointer // TODO also support XPath // Value represents either the static value of the replacem ent or an expression that will be evaluated to produce the value. Value ValueOrExpression // Extensions provides a list of extensions to the PayloadReplacement object. Extensions *extensions.Extensions // contains filtered or unexported fields }
PayloadReplacement represents a replacement of a value within a payload such as a request body.
func (*PayloadReplacement) GetCore ¶
func (p *PayloadReplacement) GetCore() *core.PayloadReplacement
GetCore will return the low level representation of the payload replacement object. Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
func (*PayloadReplacement) Validate ¶
func (p *PayloadReplacement) Validate(ctx context.Context, opts ...validation.Option) []error
Validate will validate the payload replacement object against the Arazzo specification.
type RequestBody ¶
type RequestBody struct { // ContentType is the content type of the request body ContentType *string // Payload is a static value or value containing expressions that will be used to populate the request body Payload Value // Replacements is a list of expressions that will be used to populate the request body in addition to any in the Payload field Replacements []PayloadReplacement // Extensions is a list of extensions to apply to the request body object Extensions *extensions.Extensions // contains filtered or unexported fields }
RequestBody represents the request body to pass to an operation represented by a step
func (*RequestBody) GetCore ¶
func (r *RequestBody) GetCore() *core.RequestBody
GetCore will return the low level representation of the request body object. Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
func (*RequestBody) Validate ¶
func (r *RequestBody) Validate(ctx context.Context, opts ...validation.Option) []error
Validate will validate the request body object against the Arazzo specification.
type Reusable ¶
type Reusable[T validator, C any] struct { Reference *expression.Expression Value Value Object *T // contains filtered or unexported fields }
type ReusableFailureAction ¶
type ReusableFailureAction = Reusable[FailureAction, core.FailureAction]
ReusableFailureAction represents a failure action that can either be referenced from components or declared inline in a workflow or step.
type ReusableParameter ¶
ReusableParameter represents a parameter that can either be referenced from components or declared inline in a workflow or step.
type ReusableSuccessAction ¶
type ReusableSuccessAction = Reusable[SuccessAction, core.SuccessAction]
ReusableSuccessAction represents a success action that can either be referenced from components or declared inline in a workflow or step.
type SourceDescription ¶
type SourceDescription struct { // Name is the case-sensitive name of the SourceDescription object used to reference it. Name string // URL is a URL or relative URI to the location of the referenced document. URL string // Type is the type of the referenced document. Type SourceDescriptionType // Extensions provides a list of extensions to the SourceDescription object. Extensions *extensions.Extensions // contains filtered or unexported fields }
SourceDescription represents an Arazzo or OpenAPI document that is referenced by this Arazzo document.
func (*SourceDescription) GetCore ¶
func (s *SourceDescription) GetCore() *core.SourceDescription
GetCore will return the low level representation of the source description object. Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
func (*SourceDescription) Validate ¶
func (s *SourceDescription) Validate(ctx context.Context, opts ...validation.Option) []error
Validate will validate the source description object against the Arazzo specification.
type SourceDescriptionType ¶
type SourceDescriptionType string
SourceDescriptionType represents the type of the SourceDescription object.
type SourceDescriptions ¶
type SourceDescriptions []SourceDescription
SourceDescriptions represents a list of SourceDescription objects that describe the source of the data that the workflow is orchestrating.
func (SourceDescriptions) Find ¶
func (s SourceDescriptions) Find(name string) *SourceDescription
Find will return the first SourceDescription object with the provided name.
type Step ¶
type Step struct { // StepID is a unique identifier for the step within a workflow. StepID string // Description is a description of the step. Description *string // OperationID is an operationId or expression to an operation in a SourceDescription that the step relates to. Mutually exclusive with OperationPath & WorkflowID. OperationID *expression.Expression // OperationPath is an expression to an operation in a SourceDescription that the step relates to. Mutually exclusive with OperationID & WorkflowID. OperationPath *expression.Expression // WorkflowID is a workflowId or expression to a workflow in a SourceDescription that the step relates to. Mutually exclusive with OperationID & OperationPath. WorkflowID *expression.Expression // Parameters is a list of Parameters that will be passed to the referenced operation or workflow. These will override any matching parameters defined at the workflow level. Parameters []ReusableParameter // RequestBody is the request body to be passed to the referenced operation. RequestBody *RequestBody // SuccessCriteria is a list of criteria that must be met for the step to be considered successful. SuccessCriteria []criterion.Criterion // OnSuccess is a list of SuccessActions that will be executed if the step is successful. OnSuccess []ReusableSuccessAction // OnFailure is a list of FailureActions that will be executed if the step is unsuccessful. OnFailure []ReusableFailureAction // Outputs is a list of outputs that will be returned by the step. Outputs Outputs // Extensions provides a list of extensions to the Step object. Extensions *extensions.Extensions // contains filtered or unexported fields }
Step represents a step in a workflow that describes the operation to be performed.
func (*Step) GetCore ¶
GetCore will return the low level representation of the step object. Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
type Steps ¶
type Steps []Step
Steps represents a list of Step objects that describe the operations to be performed in the workflow.
type SuccessAction ¶
type SuccessAction struct { // Name is a case-sensitive name for the SuccessAction. Name string // Type is the type of action to take on success. Type SuccessActionType // WorkflowID is the workflow/step to go to on success. Mutually exclusive to StepID. WorkflowID *expression.Expression // StepID is the workflow/step to go to on success. Mutually exclusive to WorkflowID. StepID *string // Criteria is a list of criteria that must be met for the action to be taken. Criteria []criterion.Criterion // Extensions provides a list of extensions to the SuccessAction object. Extensions *extensions.Extensions // contains filtered or unexported fields }
SuccessAction represents an action to take on success of a workflow/step.
func (*SuccessAction) GetCore ¶
func (s *SuccessAction) GetCore() *core.SuccessAction
GetCore will return the low level representation of the success action object. Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
func (SuccessAction) Validate ¶
func (s SuccessAction) Validate(ctx context.Context, opts ...validation.Option) []error
Validate will validate the success action object against the Arazzo specification. Requires an Arazzo object to be passed via validation options with validation.WithContextObject().
type SuccessActionType ¶
type SuccessActionType string
SuccessActionType represents the type of action to take on success.
const ( // SuccessActionTypeEnd indicates that the workflow/step should end. SuccessActionTypeEnd SuccessActionType = "end" // SuccessActionTypeGoto indicates that the workflow/step should go to another workflow/step on success. SuccessActionTypeGoto SuccessActionType = "goto" )
type ValueOrExpression ¶
type ValueOrExpression = *yaml.Node
ValueOrExpression represents a raw value or expression in the Arazzo document.
type VisitFunc ¶
VisitFunc represents a function that will be called for each node in the Arazzo document. The functions receives the current node, any parent nodes, and the Arazzo document. TODO would this benefit from a locator type argument that contains the key or index it is located in within a slice or map?
type Workflow ¶
type Workflow struct { // WorkflowID is a unique identifier for the workflow. WorkflowID string // Summary is a short description of the purpose of the workflow. Summary *string // Description is a longer description of the purpose of the workflow. May contain CommonMark syntax. Description *string // Parameters is a list of Parameters that will be passed to the referenced operation or workflow. Parameters []ReusableParameter // Inputs is a JSON Schema containing a set of inputs that will be passed to the referenced workflow. Inputs oas31.JSONSchema // DependsOn is a list of workflowIds (or expressions to workflows) that must succeed before this workflow can be executed. DependsOn []expression.Expression // Steps is a list of steps that will be executed in the order they are listed. Steps Steps // SuccessActions is a list of actions that will be executed by each step in the workflow if the step succeeds. Can be overridden by the step. SuccessActions []ReusableSuccessAction // FailureActions is a list of actions that will be executed by each step in the workflow if the step fails. Can be overridden by the step. FailureActions []ReusableFailureAction // Outputs is a set of outputs that will be returned by the workflow. Outputs Outputs // Extensions provides a list of extensions to the Workflow object. Extensions *extensions.Extensions // contains filtered or unexported fields }
Workflow represents a set of steps that orchestrates the execution of API calls.