Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions .mise-tasks/test-cli
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ echo " ✓ Testing help commands..."
$CLI --help > /dev/null
$CLI spec --help > /dev/null
$CLI arazzo --help > /dev/null
$CLI asyncapi --help > /dev/null
$CLI overlay --help > /dev/null

# Test all subcommands help
Expand All @@ -36,6 +37,7 @@ $CLI arazzo list-rules --help > /dev/null
$CLI arazzo graph --help > /dev/null
$CLI arazzo bootstrap --help > /dev/null
$CLI arazzo explore --help > /dev/null
$CLI asyncapi validate --help > /dev/null
$CLI overlay apply --help > /dev/null
$CLI overlay validate --help > /dev/null
$CLI overlay compare --help > /dev/null
Expand Down Expand Up @@ -203,6 +205,36 @@ if $CLI arazzo validate arazzo/testdata/sources/invalid.arazzo.yaml > /dev/null
exit 1
fi
$CLI arazzo validate --skip-sources arazzo/testdata/sources/invalid.arazzo.yaml > /dev/null
$CLI arazzo validate arazzo/testdata/sources/async-valid.arazzo.yaml > /dev/null
if $CLI arazzo validate arazzo/testdata/sources/async-invalid.arazzo.yaml > /dev/null 2>&1; then
echo " ❌ Expected arazzo validation to fail for a document that doesn't match its AsyncAPI sources"
exit 1
fi

# Test AsyncAPI validation
echo " ✓ Testing asyncapi validation..."
$CLI asyncapi validate asyncapi/testdata/streetlights-3.0.yaml > /dev/null 2>&1
$CLI asyncapi validate asyncapi/testdata/complete-3.1.yaml > /dev/null 2>&1
$CLI asyncapi validate --resolve asyncapi/testdata/validate/orders.asyncapi.yaml > /dev/null 2>&1
$CLI asyncapi validate --resolve --base-uri asyncapi/testdata/validate/orders.asyncapi.yaml < asyncapi/testdata/validate/orders.asyncapi.yaml > /dev/null 2>&1
# References to other documents aren't followed without --resolve, which is a warning that only fails with --strict
$CLI asyncapi validate asyncapi/testdata/validate/broken-ref.asyncapi.yaml > dist/test/test-asyncapi-unresolved.txt 2>&1
if ! grep -q "use --resolve to validate them" dist/test/test-asyncapi-unresolved.txt; then
echo " ❌ Expected asyncapi validate to report references it didn't follow"
exit 1
fi
if $CLI asyncapi validate --strict asyncapi/testdata/validate/orders.asyncapi.yaml > /dev/null 2>&1; then
echo " ❌ Expected asyncapi validate --strict to fail on warnings"
exit 1
fi
for f in broken-ref invalid v2; do
resolve=""
[ "$f" = "broken-ref" ] && resolve="--resolve"
if $CLI asyncapi validate $resolve asyncapi/testdata/validate/$f.asyncapi.yaml > /dev/null 2>&1; then
echo " ❌ Expected asyncapi validation to fail for $f.asyncapi.yaml"
exit 1
fi
done

# Test arazzo linting
echo " ✓ Testing arazzo lint..."
Expand Down Expand Up @@ -338,6 +370,7 @@ echo " - Validated known good and bad files"
echo " - Tested bootstrap, upgrade, inline, clean, sanitize, bundle, join commands"
echo " - Compared outputs with expected results"
echo " - Tested arazzo validation, lint, list-rules, graph and bootstrap"
echo " - Tested asyncapi validation"
echo " - Tested overlay validation, apply, and compare"
echo " - Tested error cases and edge conditions"
echo " - Validated all generated files"
19 changes: 16 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,10 @@

The `arazzo` package provides an API for working with Arazzo 1.0.x and 1.1.x documents including reading, creating, mutating, walking, validating, linting, upgrading and graphing them, and bootstrapping them from OpenAPI documents.

### [asyncapi](./asyncapi)

The `asyncapi` package provides an API for working with AsyncAPI 3.0.x and 3.1.x documents including reading, creating, mutating, walking and validating them, resolving references within and across documents, and applying operation and message traits.

### [openapi](./openapi)

The `openapi` package provides an API for working with OpenAPI documents including reading, creating, mutating, walking, validating, upgrading, and linting them. Supports OpenAPI 3.0.x, 3.1.x, and 3.2.x specifications.
Expand All @@ -86,7 +90,7 @@ The `overlay` package provides an API for working with OpenAPI Overlays includin

## CLI Tool

This repository also provides a comprehensive CLI tool for working with OpenAPI specifications, Arazzo workflows, and OpenAPI overlays.
This repository also provides a comprehensive CLI tool for working with OpenAPI specifications, Arazzo workflows, AsyncAPI documents and OpenAPI overlays.

### Installation

Expand Down Expand Up @@ -118,7 +122,7 @@ For manual installation, upgrade instructions, custom installation options, and

### Usage

The CLI provides four main command groups:
The CLI provides five main command groups:

- **`openapi spec`** - Commands for working with OpenAPI specifications ([documentation](./cmd/openapi/commands/openapi/README.md))
- `bootstrap` - Create a new OpenAPI document with best practice examples
Expand All @@ -142,14 +146,17 @@ The CLI provides four main command groups:
- `upgrade` - Upgrade a Swagger 2.0 specification to OpenAPI 3.0

- **`openapi arazzo`** - Commands for working with Arazzo workflow documents ([documentation](./cmd/openapi/commands/arazzo/README.md))
- `validate` - Validate an Arazzo workflow document, including against the OpenAPI and Arazzo documents it references
- `validate` - Validate an Arazzo workflow document, including against the OpenAPI, AsyncAPI and Arazzo documents it references
- `upgrade` - Upgrade an Arazzo workflow document to the latest supported version (1.1.0)
- `lint` - Lint an Arazzo workflow document for semantic issues, style and security concerns, with optional fixes
- `list-rules` - List the available Arazzo lint rules
- `graph` - Render the workflows of an Arazzo document as a Mermaid or Graphviz DOT diagram
- `bootstrap` - Generate starter Arazzo workflows from an OpenAPI document, or create an example Arazzo document
- `explore` - Interactively explore the workflows of an Arazzo document

- **`openapi asyncapi`** - Commands for working with AsyncAPI documents ([documentation](./cmd/openapi/commands/asyncapi/README.md))
- `validate` - Validate an AsyncAPI 3.x document, optionally following references to other files and URLs

- **`openapi overlay`** - Commands for working with OpenAPI overlays ([documentation](./cmd/openapi/commands/overlay/README.md))
- `apply` - Apply an overlay to an OpenAPI specification
- `compare` - Compare two specifications and generate an overlay describing differences
Expand Down Expand Up @@ -209,6 +216,12 @@ openapi arazzo bootstrap --from ./openapi.yaml ./workflows.arazzo.yaml
# Interactively explore the workflows of an Arazzo document
openapi arazzo explore ./workflow.arazzo.yaml

# Validate an AsyncAPI document without reading anything outside it
openapi asyncapi validate ./asyncapi.yaml

# Validate an AsyncAPI document and the files and URLs it references, failing on warnings
openapi asyncapi validate --resolve --strict ./asyncapi.yaml

# Validate a Swagger 2.0 document
openapi swagger validate ./api.swagger.yaml

Expand Down
20 changes: 16 additions & 4 deletions arazzo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,15 +21,27 @@

## Supported versions

| Arazzo version | Support |
| -------------- | ------- |
| [1.1.x](https://spec.openapis.org/arazzo/v1.1.0) | Read, write, walk and validate, including AsyncAPI steps (`channelPath`, `action`, `correlationId`), `dependsOn`, `timeout`, Selector Objects, action `parameters`, `$self` and the stricter 1.1 runtime expression grammar. AsyncAPI documents are not loaded, so references into them are only checked structurally. |
| [1.0.x](https://spec.openapis.org/arazzo/v1.0.1) | Read, write, walk and validate. |
| Arazzo version | Support |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [1.1.x](https://spec.openapis.org/arazzo/v1.1.0) | Read, write, walk and validate, including AsyncAPI steps (`channelPath`, `action`, `correlationId`), `dependsOn`, `timeout`, Selector Objects, action `parameters`, `$self` and the stricter 1.1 runtime expression grammar. AsyncAPI 3.0 and 3.1 sources are checked by `ValidateSources` (see below); AsyncAPI 2.x sources are reported as unsupported and only checked structurally. |
| [1.0.x](https://spec.openapis.org/arazzo/v1.0.1) | Read, write, walk and validate. |

Any patch release of a supported minor version is accepted (including prerelease suffixes such as `1.1.0-rc1`). Validation follows the version declared by the document, so using an Arazzo 1.1 feature in a document that declares `arazzo: 1.0.x` is reported as an error. Use `arazzo.Upgrade` (or `openapi arazzo upgrade`) to move a 1.0.x document to 1.1.0. The upgrade pins `jsonpath` and `xpath` criteria to the versions Arazzo 1.0 implied, so their meaning doesn't change.

Where the Arazzo Specification text and its JSON Schema disagree, validation follows the specification text.

### AsyncAPI sources

`LoadSourceDescriptions` loads AsyncAPI 3.0 and 3.1 sources with the [asyncapi](../asyncapi) package and resolves their references, using the same file system and HTTP client as OpenAPI sources. `ValidateSources` then checks AsyncAPI steps against them:

- `operationId` must be a key of the root `operations` map. Operations in `components` are reusable definitions, not operations of the application, so they don't match.
- `channelPath` must be a JSON Pointer to a channel's key under `/channels` or `/components/channels`, for example `{$sourceDescriptions.events.url}#/channels/orderCreated`. A channel's `address` is not its key.
- `operationPath` can't target an AsyncAPI source, as Arazzo AsyncAPI steps use `operationId` or `channelPath`.
- Header parameters should be declared by the headers schema of one of the messages the step can send or receive (the operation's `messages`, or all messages of its channel), including headers added by message traits. Other parameter locations have no AsyncAPI meaning. Both are reported as warnings.
- A `receive` step with a `requestBody`, or with a `correlationId` when none of its messages declare one, is reported as a warning.

Some things are deliberately not checked. A step's `action` isn't compared with the AsyncAPI operation's `action`, as the step describes the workflow's side of the exchange and the operation the application's, and Arazzo doesn't define how they relate. Correlation values, payloads, bindings and channel address parameters are runtime concerns. Checks that something isn't declared are skipped when a reference couldn't be resolved or a headers schema uses composition or a non JSON Schema format.

### Migrating step and workflow outputs

Arazzo 1.1 allows an output to be either a runtime expression or a Selector Object, so `arazzo.Outputs` is now a map of `*arazzo.OutputValue` instead of `expression.Expression`:
Expand Down
20 changes: 20 additions & 0 deletions arazzo/linter/rules/source_description_type_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,26 @@ func TestSourceDescriptionTypeRule_LoadedSourceFix_Success(t *testing.T) {
assert.Equal(t, arazzo.SourceDescriptionType(arazzo.SourceDescriptionTypeArazzo), a.SourceDescriptions[1].Type, "type should be set")
}

func TestSourceDescriptionTypeRule_LoadedAsyncAPISourceFix_Success(t *testing.T) {
t.Parallel()

a := parseDoc(t, sourcesDoc("1.1.0", untypedSources))
sources, loadErrs := arazzo.LoadSourceDescriptions(t.Context(), a, arazzo.LoadSourcesOptions{
VirtualFS: fstest.MapFS{
"typed.yaml": {Data: []byte("openapi: 3.1.0\ninfo:\n title: Typed\n version: 1.0.0\n")},
"untyped.yaml": {Data: []byte("asyncapi: 3.0.0\ninfo:\n title: Events\n version: 1.0.0\n")},
},
})
require.Empty(t, loadErrs, "sources should load")

fix := sourceTypeFix(t, a, sources)
assert.False(t, fix.Interactive(), "fix should not need input when the source was loaded")
assert.Equal(t, "Set the type of sourceDescription `untyped` to `asyncapi`", fix.Description(), "description should match")

require.NoError(t, fix.Apply(a), "fix should apply")
assert.Equal(t, arazzo.SourceDescriptionType(arazzo.SourceDescriptionTypeAsyncAPI), a.SourceDescriptions[1].Type, "type should be set")
}

func TestSourceDescriptionTypeRule_InteractiveFix_Success(t *testing.T) {
t.Parallel()

Expand Down
66 changes: 51 additions & 15 deletions arazzo/sources.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,10 @@ import (
"io"
"net/http"
"path/filepath"
"strings"
"time"

"github.com/speakeasy-api/openapi/asyncapi"
"github.com/speakeasy-api/openapi/internal/utils"
"github.com/speakeasy-api/openapi/openapi"
"github.com/speakeasy-api/openapi/system"
Expand Down Expand Up @@ -45,6 +47,8 @@ type SourceDocument struct {
OpenAPI *openapi.OpenAPI
// Arazzo is the loaded document if it is an Arazzo document.
Arazzo *Arazzo
// AsyncAPI is the loaded document if it is an AsyncAPI 3.x document, with its references resolved.
AsyncAPI *asyncapi.AsyncAPI
}

// SourceDocuments are the documents loaded for an Arazzo document's sourceDescriptions, keyed by source description name.
Expand All @@ -60,12 +64,13 @@ func (s *SourceDocuments) Get(name string) *SourceDocument {
return s.documents[name]
}

// LoadSourceDescriptions loads the OpenAPI and Arazzo documents referenced by the Arazzo document's
// LoadSourceDescriptions loads the OpenAPI, AsyncAPI and Arazzo documents referenced by the Arazzo document's
// sourceDescriptions so the document can be validated against them with ValidateSources.
//
// Problems loading a source are returned as warnings rather than errors, as a source may be temporarily
// unavailable without the Arazzo document being invalid. AsyncAPI sources are not loaded and are reported with
// a hint. A source description declaring a type that doesn't match the loaded document is reported as an error.
// unavailable without the Arazzo document being invalid. This includes AsyncAPI documents of a version the asyncapi
// package doesn't support, such as 2.x. A source description declaring a type that doesn't match the loaded document
// is reported as an error.
func LoadSourceDescriptions(ctx context.Context, a *Arazzo, opts LoadSourcesOptions) (*SourceDocuments, []error) {
sources := &SourceDocuments{documents: map[string]*SourceDocument{}}
if a == nil {
Expand Down Expand Up @@ -114,10 +119,6 @@ func loadSourceDescription(ctx context.Context, sd *SourceDescription, base stri
return []error{validation.NewValueError(validation.SeverityWarning, validation.RuleValidationInvalidReference, err, core, core.URL)}
}

if sd.Type == SourceDescriptionTypeAsyncAPI {
return nil, []error{asyncAPINotCheckedHint(sd)}
}

location, err := resolveSourceLocation(base, sd.URL)
if err != nil {
return nil, warn(fmt.Errorf("sourceDescription `%s` url can't be resolved: %w", sd.Name, err))
Expand All @@ -134,21 +135,26 @@ func loadSourceDescription(ctx context.Context, sd *SourceDescription, base stri
return nil, warn(fmt.Errorf("sourceDescription `%s` at `%s` is not an OpenAPI 3.x, AsyncAPI or Arazzo document", sd.Name, location))
case sd.Type != "" && sd.Type != detected:
return nil, []error{validation.NewValueError(validation.SeverityError, validation.RuleValidationTypeMismatch, fmt.Errorf("sourceDescription `%s` is declared as type `%s` but `%s` is an %s document", sd.Name, sd.Type, location, detected), core, core.Type)}
case detected == SourceDescriptionTypeAsyncAPI:
return nil, []error{asyncAPINotCheckedHint(sd)}
}

doc := &SourceDocument{Name: sd.Name, Location: location, Type: detected}

if detected == SourceDescriptionTypeArazzo {
switch detected {
case SourceDescriptionTypeArazzo:
doc.Arazzo, _, err = Unmarshal(ctx, bytes.NewReader(data), WithSkipValidation())
} else {
case SourceDescriptionTypeAsyncAPI:
doc.AsyncAPI, _, err = asyncapi.Unmarshal(ctx, bytes.NewReader(data), asyncapi.WithSkipValidation())
default:
doc.OpenAPI, _, err = openapi.Unmarshal(ctx, bytes.NewReader(data), openapi.WithSkipValidation())
}
if err != nil {
return nil, warn(fmt.Errorf("sourceDescription `%s` at `%s` could not be parsed: %w", sd.Name, location, err))
}
if doc.OpenAPI == nil {

switch {
case doc.AsyncAPI != nil:
return loadAsyncAPISource(ctx, doc, opts, warn)
case doc.OpenAPI == nil:
return doc, nil
}

Expand All @@ -173,9 +179,39 @@ func resolveSourceLocation(base, ref string) (string, error) {
return utils.JoinReference(base, ref)
}

func asyncAPINotCheckedHint(sd *SourceDescription) error {
core := sd.GetCore()
return validation.NewValueError(validation.SeverityHint, validation.RuleValidationInvalidReference, fmt.Errorf("sourceDescription `%s` is an AsyncAPI document, steps targeting it are not checked against the source", sd.Name), core, core.URL)
// loadAsyncAPISource checks the AsyncAPI version is supported and resolves the document's references.
func loadAsyncAPISource(ctx context.Context, doc *SourceDocument, opts LoadSourcesOptions, warn func(error) []error) (*SourceDocument, []error) {
if version := doc.AsyncAPI.GetAsyncAPI(); !asyncapi.IsSupportedVersion(version) {
return nil, warn(fmt.Errorf("sourceDescription `%s` is an AsyncAPI %s document, only AsyncAPI %s are supported so steps targeting it are not checked", doc.Name, version, strings.Join(asyncapi.SupportedMinorVersions(), " and ")))
}

// Unresolved references only reduce how much can be checked, so the source is still usable.
resolveErrs, err := doc.AsyncAPI.ResolveAllReferences(ctx, asyncapi.ResolveAllOptions{
AsyncAPILocation: doc.Location,
VirtualFS: opts.VirtualFS,
HTTPClient: opts.HTTPClient,
})
if err == nil {
err = firstResolutionError(resolveErrs)
}
if err != nil {
return doc, warn(fmt.Errorf("sourceDescription `%s` has references that could not be resolved, some checks may be skipped: %w", doc.Name, err))
}

return doc, nil
}

// firstResolutionError returns the first error from resolving an AsyncAPI document's references. Warnings and hints,
// such as schema formats that aren't validated, don't stop anything being checked so they are ignored.
func firstResolutionError(errs []error) error {
for _, err := range errs {
var vErr *validation.Error
if errors.As(err, &vErr) && vErr.Severity != validation.SeverityError {
continue
}
return err
}
return nil
}

func fetchSource(ctx context.Context, location string, opts LoadSourcesOptions) ([]byte, error) {
Expand Down
Loading
Loading