Skip to content

Commit

Permalink
chore: add arazzo examples (#33)
Browse files Browse the repository at this point in the history
  • Loading branch information
DmitryAnansky authored Jul 19, 2024
1 parent 2c2ede6 commit 6db4b2d
Show file tree
Hide file tree
Showing 4 changed files with 180 additions and 4 deletions.
26 changes: 23 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@

An imaginary, but delightful Museum API for interacting with museum services and information.
Built by Redocly for educational purposes.
Enjoy!

> [!NOTE]
> This OpenAPI description uses the [OpenAPI 3.1.0 specification](https://spec.openapis.org/oas/v3.1.0).
Expand All @@ -15,9 +14,14 @@ New functionality may be added to the Museum API in the future.
Is there an example you'd like to see? Please [open an issue](https://github.com/Redocly/museum-openapi-example/issues/new).

## Features

> [!NOTE]
> Reminder that this is a fictional example for learning purposes.
> The features below are only for learning.
> Reminder that these are fictional examples for learning purposes.
> The contents of this repository are illustrations to use with your OpenAPI study or tools exploration.
### OpenAPI

- `openapi.yaml` contains the Museum API. It is an OpenAPI 3.1.0 description.

The Museum API has the following core features (sorted by tags):
- Operations
Expand All @@ -31,6 +35,11 @@ The Museum API has the following core features (sorted by tags):
- Purchase museum tickets for general entry or special events
- Get scannable QR code for museum ticket

### Arazzo

- `arazzo/museum-tickets.arazzo.yaml` is an Arazzo 1.0.0 description of using the Museum OpenAPI source to describe an API sequence.
- `arazzo/museum-api.arazzo.yaml` is an Arazzo 1.0.0 description using both the Museum API and another Arazzo file to describe a series of multi-step API workflows and passing the variables between them.

## Getting started

1. Clone this repo.
Expand All @@ -43,23 +52,28 @@ We encourage you to explore the museum's OpenAPI description and make changes.
Try experimenting with the following approaches:

**Preview the Museum OpenAPI example's API docs and observe your changes visually.**

- Run `npm run preview` to preview the documentation.
- Navigate to the **List special events** operation in the preview.
- With the preview running...
- Go to the _openapi.yaml_ file in your IDE.
- Search for `listSpecialEvents` to find the matching `operationId`.
- Replace the `description` field with the snippet below:

```yaml
description: |-
Return a list of _upcoming_ special events at the museum.
See one you like? Use this API to [buy a ticket](/#tag/Tickets/operation/buyMuseumTickets).
```
See the updated description? This is a great way to preview how end-users of your docs will experience your changes.
**Lint your changes to the OpenAPI description using [Redocly CLI](https://redocly.com/docs/cli/).**
- Open the museum's _openapi.yaml_ file in your IDE.
- Add the following snippet to `paths` above the /museum-hours operation:

```yaml
/example:
get:
Expand All @@ -71,8 +85,14 @@ See the updated description? This is a great way to preview how end-users of you
'400':
description: Bad Request
```

- Run `npm run lint` in your terminal. See the errors?

The linting behavior is controlled by the _redocly.yaml_ configuration file.
The linter is configured to use Redocly's [recommended ruleset](https://redocly.com/docs/cli/rules/recommended/#recommended-ruleset), which are built into the CLI.
However, we also added a [configurable rule](https://redocly.com/docs/cli/rules/configurable-rules/) for enforcing sentence casing on operation summaries.

**Lint an Arazzo description using [Redocly CLI](https://redocly.com/docs/cli/).**

- Redocly CLI can also lint formats other than OpenAPI, such as the Arazzo format.
- Run `npm run lint arazzo/museum-api.arazzo.yaml` to lint an example Arazzo description.
119 changes: 119 additions & 0 deletions arazzo/museum-api.arazzo.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
arazzo: 1.0.0
info:
title: Redocly Museum API Test Workflow
description: >-
Use the Museum API with Arazzo as an example of describing multi-step workflows.
Built with love by Redocly.
version: 1.0.0

sourceDescriptions:
- name: museum-api
type: openapi
url: ../openapi.yaml
- name: tickets-from-museum-api
type: arazzo
url: arazzo/museum-tickets.arazzo.yaml

workflows:
- workflowId: get-museum-hours
description: >-
This workflow demonstrates how to get the museum opening hours and buy tickets.
parameters:
- in: header
name: Authorization
value: Basic Og==
steps:
- stepId: get-museum-hours
description: >-
Get museum hours by resolving request details with getMuseumHours operationId from openapi.yaml description.
operationId: museum-api.getMuseumHours
successCriteria:
- condition: $statusCode == 200
outputs:
schedule: $response.body
- stepId: buy-ticket
description: >-
Buy a ticket for the museum by calling an external workflow from another Arazzo file.
workflowId: $sourceDescriptions.tickets-from-museum-api.workflows.get-museum-tickets
outputs:
ticketId: $outputs.ticketId
- workflowId: events-crud
description: >-
This workflow demonstrates how to list, create, update, and delete special events at the museum.
parameters:
- in: header
name: Authorization
value: Basic Og==
steps:
- stepId: list-events
description: >-
Request the list of events.
operationPath: $sourceDescriptions.museum-api#/paths/~1special-events/get
outputs:
events: $response.body
- stepId: create-event
description: >-
Create a new special event.
operationPath: $sourceDescriptions.museum-api#/paths/~1special-events/post
requestBody:
payload:
name: 'Mermaid Treasure Identification and Analysis'
location: 'Under the seaaa 🦀 🎶 🌊.'
eventDescription: 'Join us as we review and classify a rare collection of 20 thingamabobs, gadgets, gizmos, whoosits, and whatsits, kindly donated by Ariel.'
dates:
- '2023-09-05'
- '2023-09-08'
price: 0
successCriteria:
- condition: $statusCode == 201
- context: $response.body
condition: $.name == 'Mermaid Treasure Identification and Analysis'
type: jsonpath
outputs:
createdEventId: $response.body.eventId
name: $response.body.name
- stepId: get-event-by-id
description: >-
Get the details of the event that was created in the previous step.
operationPath: $sourceDescriptions.museum-api#/paths/~1special-events~1{eventId}/get
parameters:
- name: eventId
in: path
value: $steps.create-event.outputs.createdEventId
successCriteria:
- context: $statusCode
condition: '^200$'
type: regex
- stepId: update-event
description: >-
Update the created event with new details.
operationPath: $sourceDescriptions.museum-api#/paths/~1special-events~1{eventId}/patch
parameters:
- name: eventId
in: path
value: $steps.create-event.outputs.createdEventId
requestBody:
payload:
name: 'Orca Identification and Analysis'
location: 'Under the seaaa 🦀 🎶 🌊.'
dates:
- '2023-09-05'
- '2023-09-08'
price: 0
successCriteria:
- condition: $statusCode == 200
- context: $response.body
condition: $.name == 'Orca Identification and Analysis'
type: jsonpath
outputs:
updatedEventId: $response.body.eventId
- stepId: delete-event
description: >-
Delete the event that was updated in the previous step.
operationPath: $sourceDescriptions.museum-api#/paths/~1special-events~1{eventId}/delete
parameters:
- name: eventId
in: path
value: $steps.update-event.outputs.updatedEventId
successCriteria:
- condition: $statusCode == 204
37 changes: 37 additions & 0 deletions arazzo/museum-tickets.arazzo.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
arazzo: 1.0.0
info:
title: Redocly Museum Tickets Workflow
description: >-
Use the Museum API as an example in a simple Arazzo workflow.
Built with love by Redocly.
version: 1.0.0

sourceDescriptions:
- name: museum-api
type: openapi
url: ../openapi.yaml

workflows:
- workflowId: get-museum-tickets
description: >-
This workflow demonstrates how to buy tickets for the museum.
parameters:
- in: header
name: Authorization
value: Basic Og==
steps:
- stepId: buy-tickets
description: >-
Buy museum tickets resolving request details with buyMuseumTickets operationId from openapi.yaml description.
operationId: buyMuseumTickets
requestBody:
payload:
ticketType: general
ticketDate: 2023-09-07
email: [email protected]
successCriteria:
- condition: $statusCode == 201
outputs:
ticketId: $response.body.ticketId
outputs:
ticketId: $steps.buy-tickets.outputs.ticketId
2 changes: 1 addition & 1 deletion openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ info:
name: MIT
url: "https://opensource.org/license/mit/"
servers:
- url: "https://api.fake-museum-example.com/v1.1"
- url: "https://redocly.com/_mock/docs/openapi/museum-api"
paths:
/museum-hours:
get:
Expand Down

0 comments on commit 6db4b2d

Please sign in to comment.