Conversation
❌ Deploy Preview for bump-content-hub failed. Why did it fail? →
|
grossyoan
left a comment
grossyoan
left a comment
There was a problem hiding this comment.
Hi there!
Some small typos/additions on the first pages ready to review. It's a great piece of work 🙏
src/_guides/arazzo/specification/v1.0/introduction/what-is-arazzo.md
Outdated
Show resolved
Hide resolved
src/_guides/arazzo/specification/v1.0/introduction/what-is-arazzo.md
Outdated
Show resolved
Hide resolved
src/_guides/arazzo/specification/v1.0/understanding-structure/components-and-references.md
Outdated
Show resolved
Hide resolved
…zzo.md Co-authored-by: Yoan Gross <32864409+grossyoan@users.noreply.github.com>
…zzo.md Co-authored-by: Yoan Gross <32864409+grossyoan@users.noreply.github.com>
grossyoan
left a comment
grossyoan
left a comment
There was a problem hiding this comment.
Thanks a lot for the hard work, Phil 🙏
| - TOC | ||
| {:toc} | ||
|
|
||
| Source descriptions are how Arazzo gets a leg up pn understanding the APIs being worked with. To avoid repeating all the HTTP-level bits like endpoints, status codes, schema, etc. Arazzo just defines source description, then references operations by their `operationId`. Mostly these will be OpenAPI descriptions, but other Arazzo documents can also be used to reference workflows defined elsewhere, and soon AsyncAPI documents will be supported too. |
There was a problem hiding this comment.
| Source descriptions are how Arazzo gets a leg up pn understanding the APIs being worked with. To avoid repeating all the HTTP-level bits like endpoints, status codes, schema, etc. Arazzo just defines source description, then references operations by their `operationId`. Mostly these will be OpenAPI descriptions, but other Arazzo documents can also be used to reference workflows defined elsewhere, and soon AsyncAPI documents will be supported too. | |
| Source descriptions are how Arazzo gets a leg up on understanding the APIs being worked with. To avoid repeating all the HTTP-level bits like endpoints, status codes, schema, etc. Arazzo just defines source description, then references operations by their `operationId`. Mostly these will be OpenAPI descriptions, but other Arazzo documents can also be used to reference workflows defined elsewhere, and soon AsyncAPI documents will be supported too. |
There was a problem hiding this comment.
I think the introduction might be a bit heavy to read. Could it be simplified a bit? The infos are here (source descriptions avoid duplication, and reference OpenAPI & Arazzo documents), but the sentence flow could probably be a bit smoother.
| - TOC | ||
| {:toc} | ||
|
|
||
| Think of workflows as recipes for API operations. Just like a recipe breaks down cooking into steps (chop onions, sauté garlic, add tomatoes), an Arazzo workflow breaks down complex API tasks into manageable steps. If you've used GitHub Actions or Jenkins pipelines, the concept will feel familiar, but Arazzo is purpose-built for API orchestration rather than CI/CD. |
|
|
||
| ### Complex Input Types | ||
|
|
||
| Inputs can be as simple or complex as you need. Nested objects, arrays, enums,JSON Schema has a keyword for pretty much everything. |
There was a problem hiding this comment.
| Inputs can be as simple or complex as you need. Nested objects, arrays, enums,JSON Schema has a keyword for pretty much everything. | |
| Inputs can be as simple or complex as you need. Nested objects, arrays, enums, JSON Schema has a keyword for pretty much everything. |
|
|
||
| ## Workflow Outputs | ||
|
|
||
| Workflows should return useful data. What good is running a booking workflow if you can't get the booking ID back? Outputs define what data the workflow makes available to whatever called it. |
There was a problem hiding this comment.
We could maybe be a bit more specific here? Instead of "whatever called it" (meaning humans or agents I'm guessing), saying "data the workflow makes available upon completion"?
|
|
||
| ### Required Fields | ||
|
|
||
| **stepId** |
There was a problem hiding this comment.
Could we do **stepId** - The unique name for this step within the workflow. instead, like you did in workflow items?
So we don't have these weird margins.
| # ... notify about validation issues | ||
| ``` | ||
|
|
||
| ## Example: Multi-Passenger Validation |
There was a problem hiding this comment.
| ## Example: Multi-Passenger Validation | |
| ### Multi-Passenger Validation |
| ``` | ||
|
|
||
|
|
||
| ### Validate Business Rules, Not Just HTTP |
There was a problem hiding this comment.
I'm guessing it's made to be under a "Best practices" section?
| ## Component Types | ||
|
|
||
| Arazzo supports several component types, each designed to reduce repetition and make workflows easier to maintain. | ||
|
|
There was a problem hiding this comment.
We might want to add an "Inputs" title here with a few sentences to have it in the table of contents on the right.
|
|
||
| A parameter is considered unique by the combination of its `name` and `in` fields, so give it a sensible name and don't have two parameters with the same name in the same location. | ||
|
|
||
| ```yaml |
There was a problem hiding this comment.
We might want to display in: header, in:query, in:path, and in:cookie in the code sample.
|
|
||
| ## Null Safety | ||
|
|
||
| Check for null values in conditions: |
There was a problem hiding this comment.
Should it be under "Operators in Conditions"?
2 participants
The Arazzo Specification Guide is taking form.
Introduction
Understanding Structure
Working with Arazzo