diff --git a/README.md b/README.md index 1d160b7..c9c914d 100644 --- a/README.md +++ b/README.md @@ -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). @@ -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 @@ -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. @@ -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: @@ -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. diff --git a/arazzo/museum-api.arazzo.yaml b/arazzo/museum-api.arazzo.yaml new file mode 100644 index 0000000..e4a1400 --- /dev/null +++ b/arazzo/museum-api.arazzo.yaml @@ -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 diff --git a/arazzo/museum-tickets.arazzo.yaml b/arazzo/museum-tickets.arazzo.yaml new file mode 100644 index 0000000..1f1b101 --- /dev/null +++ b/arazzo/museum-tickets.arazzo.yaml @@ -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: todd@example.com + successCriteria: + - condition: $statusCode == 201 + outputs: + ticketId: $response.body.ticketId + outputs: + ticketId: $steps.buy-tickets.outputs.ticketId diff --git a/openapi.yaml b/openapi.yaml index 3a4effc..2300a32 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -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: