Skip to content

Commit d49ac9c

Browse files
frankkilcomminsfrankkilcommins
authored
add initial Arazzo tools from Jentic (#700)
1 parent c1ada15 commit d49ac9c

4 files changed

Lines changed: 320 additions & 0 deletions

File tree

‎src/content/tools/jentic-arazzo-editor.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
name: Arazzo Editor
3+
description: |
4+
Build and edit Arazzo workflows with form-based editing and real-time
5+
diagrammatic representation. Export valid Arazzo 1.0.1 YAML, JSON,
6+
markdown, or HTML documents.
7+
categories:
8+
- text-editors-extensions
9+
- docs
10+
- ides
11+
link: https://jentic.com/arazzo-editor
12+
languages:
13+
typescript: true
14+
oaiSpecs:
15+
oas: true
16+
overlays: false
17+
arazzo: true
18+
oasVersions:
19+
v2: true
20+
v3: true
21+
v3_1: true
22+
v3_2: true
23+
badges:
24+
- arazzo-support
25+
---
26+
27+
## Overview
28+
29+
Arazzo Editor is a free browser-based workflow authoring tool with form-based editing, live visual feedback, and optional code editing for power users. Build Arazzo workflows through structured forms while watching the execution diagram update in real-time — no YAML syntax required.
30+
31+
Think Stoplight Studio for APIs, but for multi-step workflow orchestration.
32+
33+
## Features
34+
35+
- **Form-based editing**: Add steps, configure parameters, define success criteria, and set up retry logic through structured forms
36+
- **Live diagram updates**: Visual representation updates in real-time as you build, showing execution paths and dependencies
37+
- **Code editing for power users**: Direct YAML/JSON editing with bidirectional synchronisation back to forms
38+
- **Export multiple formats**: Valid Arazzo 1.0.1 YAML/JSON documents, plus markdown or HTML for documentation and human review
39+
- **Full spec compliance**: No proprietary extensions, works with any Arazzo-compliant orchestrator
40+
41+
## Usage
42+
43+
**Web interface**: Visit https://jentic.com/arazzo-editor to start building workflows. Load existing Arazzo documents to evolve them, or create new workflows from scratch.
44+
45+
**Building a workflow**:
46+
47+
1. Add steps by selecting API operations from referenced OpenAPI specifications
48+
2. Configure parameters using runtime expressions like `$inputs.userId` or `$steps.auth.outputs.token`
49+
3. Define success criteria and failure handling (retry logic, goto actions, error paths)
50+
4. Watch the live diagram update as you build, showing execution flow
51+
5. Export valid Arazzo YAML or JSON when complete
52+
53+
**Power user workflow**: Switch to code view for bulk operations, copy/paste step definitions, or direct YAML editing. Changes sync back to forms immediately.

‎src/content/tools/jentic-arazzo-parser.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
name: Arazzo Parser
3+
description: |
4+
TypeScript/JavaScript parser for Arazzo Specification documents.
5+
Parses Arazzo 1.0.0 and 1.0.1 documents from objects, strings,
6+
file paths, or URLs into a structured ApiDOM data model.
7+
categories:
8+
- parsers
9+
link: https://www.npmjs.com/package/@jentic/arazzo-parser
10+
languages:
11+
typescript: true
12+
javascript: true
13+
repo: https://github.com/jentic/jentic-arazzo-tools/tree/main/packages/jentic-arazzo-parser
14+
oaiSpecs:
15+
oas: true
16+
overlays: false
17+
arazzo: true
18+
oasVersions:
19+
v2: true
20+
v3: true
21+
v3_1: true
22+
v3_2: false
23+
badges:
24+
- arazzo-support
25+
---
26+
27+
## Overview
28+
29+
`@jentic/arazzo-parser` is a TypeScript/JavaScript library for parsing Arazzo Specification documents. It produces a structured [SpecLynx ApiDOM](https://github.com/speclynx/apidom) data model using the Arazzo 1.x namespace, giving programmatic access to workflows, steps, source descriptions, and runtime expressions.
30+
31+
Accepts multiple input types — plain JavaScript objects, JSON/YAML strings, local file paths, and HTTP(S) URLs — and returns a `ParseResultElement` for further processing.
32+
33+
## Installation
34+
35+
```bash
36+
npm install @jentic/arazzo-parser
37+
```
38+
39+
## Usage
40+
41+
```typescript
42+
import { parseArazzo } from '@jentic/arazzo-parser';
43+
44+
// Parse from object, string, file path, or URL
45+
const parseResult = await parseArazzo(source);
46+
47+
const arazzoSpec = parseResult.api; // ArazzoSpecification1Element
48+
const hasErrors = parseResult.errors.length > 0;
49+
```
50+
51+
**Supported inputs:**
52+
53+
- Plain JavaScript object
54+
- JSON or YAML string
55+
- Local file system path
56+
- HTTP(S) URL
57+
58+
**Parse options:**
59+
60+
```typescript
61+
const parseResult = await parseArazzo(source, {
62+
parse: {
63+
parserOpts: {
64+
strict: true, // strict parsing mode (default: true)
65+
sourceMap: false, // include source maps (default: false)
66+
},
67+
},
68+
});
69+
```
70+
71+
**Error handling:**
72+
73+
```typescript
74+
try {
75+
await parseArazzo('invalid content');
76+
} catch (error) {
77+
console.error(error.message); // 'Failed to parse Arazzo Document'
78+
console.error(error.cause); // original underlying error
79+
}
80+
```
81+
82+
## Supported Versions
83+
84+
| Spec | Versions |
85+
| ------- | ----------------- |
86+
| Arazzo | 1.0.0, 1.0.1 |
87+
| OpenAPI | 2.0, 3.0.x, 3.1.x |

‎src/content/tools/jentic-arazzo-resolver.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
name: Arazzo Resolver
3+
description: |
4+
TypeScript/JavaScript resolver and dereferencer for Arazzo Specification
5+
and OpenAPI documents. Resolves all internal and external references
6+
inline, producing self-contained ApiDOM data models.
7+
categories:
8+
- parsers
9+
- misc
10+
link: https://www.npmjs.com/package/@jentic/arazzo-resolver
11+
languages:
12+
typescript: true
13+
javascript: true
14+
repo: https://github.com/jentic/jentic-arazzo-tools/tree/main/packages/jentic-arazzo-resolver
15+
oaiSpecs:
16+
oas: true
17+
overlays: false
18+
arazzo: true
19+
oasVersions:
20+
v2: true
21+
v3: true
22+
v3_1: true
23+
v3_2: false
24+
badges:
25+
- arazzo-support
26+
---
27+
28+
## Overview
29+
30+
`@jentic/arazzo-resolver` is a TypeScript/JavaScript library for resolving and dereferencing Arazzo Specification and OpenAPI documents. It replaces all references (`$ref`, `$components.*`, JSON Schema references) with their actual content, producing self-contained [SpecLynx ApiDOM](https://github.com/speclynx/apidom) data models ready for programmatic processing.
31+
32+
Works standalone from a file path or URL, or in combination with `@jentic/arazzo-parser` to dereference already-parsed elements.
33+
34+
## Installation
35+
36+
```bash
37+
npm install @jentic/arazzo-resolver
38+
```
39+
40+
## Usage
41+
42+
**Dereference from a file path or URL:**
43+
44+
```typescript
45+
import { dereferenceArazzo } from '@jentic/arazzo-resolver';
46+
47+
// Local file
48+
const parseResult = await dereferenceArazzo('/path/to/arazzo.json');
49+
50+
// Remote URL
51+
const parseResult = await dereferenceArazzo('https://example.com/arazzo.yaml');
52+
// parseResult is a ParseResultElement with all references resolved inline
53+
```
54+
55+
**Dereference an already-parsed element (with `@jentic/arazzo-parser`):**
56+
57+
```typescript
58+
import { parseArazzo } from '@jentic/arazzo-parser';
59+
import { dereferenceArazzoElement } from '@jentic/arazzo-resolver';
60+
61+
const parseResult = await parseArazzo('/path/to/arazzo.json');
62+
const dereferenced = await dereferenceArazzoElement(parseResult);
63+
```
64+
65+
**Dereference inline content — provide a `baseURI`:**
66+
67+
```typescript
68+
import { parseArazzo } from '@jentic/arazzo-parser';
69+
import { dereferenceArazzoElement } from '@jentic/arazzo-resolver';
70+
71+
const parseResult = await parseArazzo({ arazzo: '1.0.1', ... });
72+
const dereferenced = await dereferenceArazzoElement(parseResult, {
73+
resolve: { baseURI: 'https://example.com/arazzo.json' },
74+
});
75+
```
76+
77+
**Dereference a specific child element (e.g. a single workflow):**
78+
79+
```typescript
80+
import { parseArazzo } from '@jentic/arazzo-parser';
81+
import { dereferenceArazzoElement } from '@jentic/arazzo-resolver';
82+
83+
const parseResult = await parseArazzo('/path/to/arazzo.json');
84+
const workflow = parseResult.api.workflows.get(0);
85+
86+
const dereferencedWorkflow = await dereferenceArazzoElement(workflow, {
87+
dereference: { strategyOpts: { parseResult } },
88+
});
89+
```
90+
91+
**OpenAPI documents:**
92+
93+
```typescript
94+
import { dereferenceOpenAPI } from '@jentic/arazzo-resolver';
95+
96+
const parseResult = await dereferenceOpenAPI('/path/to/openapi.yaml');
97+
```
98+
99+
## API
100+
101+
| Function | Description |
102+
| ------------------------------------------- | ------------------------------------------------------- |
103+
| `dereferenceArazzo(uri)` | Dereference an Arazzo document from a file path or URL |
104+
| `dereferenceArazzoElement(element, opts?)` | Dereference a SpecLynx ApiDOM Arazzo element |
105+
| `dereferenceOpenAPI(uri)` | Dereference an OpenAPI document from a file path or URL |
106+
| `dereferenceOpenAPIElement(element, opts?)` | Dereference a SpecLynx ApiDOM OpenAPI element |
107+
108+
## What Gets Resolved
109+
110+
**In Arazzo documents:**
111+
112+
- JSON Schema references
113+
- Reusable object references (`$components.*`)
114+
115+
**In OpenAPI documents:**
116+
117+
- Reference Objects (`$ref`) — components, external files, URLs
118+
- JSON Schema references
119+
- Path Item Objects
120+
- and others
121+
122+
## Supported Versions
123+
124+
| Spec | Versions |
125+
| ------- | ----------------- |
126+
| Arazzo | 1.0.0, 1.0.1 |
127+
| OpenAPI | 2.0, 3.0.x, 3.1.x |

‎src/content/tools/jentic-arazzo-ui.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
name: Arazzo UI
3+
description: |
4+
Visualize Arazzo workflows as interactive documentation. It provides diagram views, documentation views, and a split view combining both
5+
categories:
6+
- docs
7+
link: https://arazzo-ui.jentic.com/
8+
languages:
9+
cli: true
10+
typescript: true
11+
repo: https://github.com/jentic/jentic-arazzo-tools/tree/main/packages/jentic-arazzo-ui
12+
oaiSpecs:
13+
oas: true
14+
overlays: false
15+
arazzo: true
16+
oasVersions:
17+
v2: true
18+
v3: true
19+
v3_1: true
20+
v3_2: false
21+
badges:
22+
- arazzo-support
23+
---
24+
25+
## Overview
26+
27+
Arazzo UI is an open-source tool for visualizing Arazzo workflow documents. It renders YAML or JSON workflow definitions as sequence diagrams, flow charts, and structured documentation—making multi-step API orchestration logic accessible without parsing raw specifications.
28+
29+
Load local files or share remote workflows via URL with no configuration required. Think SwaggerUI or Scalar for OpenAPI, but for API workflows.
30+
31+
## Features
32+
33+
- **Multiple visualization modes**: Sequence diagrams, flow diagrams, and documentation views
34+
- **Remote workflow loading**: Share workflows via URL using the `document` query parameter
35+
- **Command-line support**: Open workflows directly from terminal with `npx @jentic/arazzo-ui [url]`
36+
- **No setup required**: Browser-based, zero configuration
37+
- **Full Arazzo 1.0.1 support**: Renders all workflow elements including steps, dependencies, success/failure paths, and retry logic
38+
39+
## Usage
40+
41+
**Web Interface:**
42+
Visit https://arazzo-ui.jentic.com and upload a local Arazzo document or paste a URL to a remote workflow.
43+
44+
**Share workflows via URL:**
45+
https://arazzo-ui.jentic.com?document=https://your-domain.com/workflow.arazzo.yaml
46+
47+
**Command line:**
48+
49+
```bash
50+
npx @jentic/arazzo-ui https://example.com/workflow.arazzo.yaml
51+
52+
Opens the workflow in your default browser for visualization.
53+
```

0 commit comments

Comments
 (0)