redocly / museum-openapi-example Goto Github PK

An example OpenAPI description for an imaginary Museum API.

Home Page: https://redocly.com/docs/resources/learning-openapi/

License: MIT License

apis example openapi openapi-sp openapi-spec openapi3 rest oas-description openapi-description openapi-example

museum-openapi-example's Introduction

Redocly Museum API Example

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.

Overview

Introducing the "Museum API", which offers a set of endpoints to interact with a museum's services--such as retrieving museum hours, managing special events, and purchasing tickets.

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.

Features

Note

Reminder that this is a fictional example for learning purposes. The features below are only for learning.

The Museum API has the following core features (sorted by tags):

Operations
- Get museum operational hours
Special events
- Get special event data
- List special events
- Create and update a special event
- Delete a special event
Tickets
- Purchase museum tickets for general entry or special events
- Get scannable QR code for museum ticket

Getting started

Clone this repo.
Open the repo in your IDE.
Run npm install to install the Redocly CLI.

Working with the OpenAPI description

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:

    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.

Open the museum's openapi.yaml file in your IDE.
Add the following snippet to paths above the /museum-hours operation:

  /example:
    get: 
      summary: Example Summary
      description: Example description
      responses: 
        '200':
          description: Success
        '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, which are built into the CLI. However, we also added a configurable rule for enforcing sentence casing on operation summaries.

museum-openapi-example's People

Contributors

Stargazers

Watchers

museum-openapi-example's Issues

License

I noticed the license inside of the openapi.yaml (Apache 2) mismatches the license in the repo (MIT). Should we align to MIT?

Update openapi.yaml with linting fixes

When replacing the Petstore API with the Musuem API in the Redocly monorepo, our linting found some issues in the API like missing punctuation, quotation marks, etc, that needed to be updated. So this issue is to make those minor updates and moves the repeated 400 errors into the components section so that $refs can be used.

license URL has trailing space

The source openapi.yaml contains

  license:
    name: MIT
    url: "https://opensource.org/license/mit/ "

with a trailing space. This should be

  license:
    name: MIT
    url: "https://opensource.org/license/mit/"

(I can submit a PR to fix this)

Tag endpoints to separate staff and user operations

We have both staff and user endpoints in the Museum API. Tag them separately and show an example of filtering (see: https://redocly.com/docs/cli/decorators/filter-in/) just one of the tags into a bundle.

Add Membership operations to the Museum example

Museums often offer annual memberships to guest with special perks. This could be implemented into the spec.

Some methods could include:

Add member
Update member
Change membership
upgrade membership
downgrade membership
cancel membership
Find member
Apply member discount

add membership level
update membership level

Run prettier automatically

I ran prettier to make the API description more consistent, but we should automate that so it runs every time.

Update issue template

The issue template is the default one we use on our code projects, which isn't a great fit for a community-driven participation repository. Let's update it to be welcoming and relevant.

Consider `oauth2` or `openIdConnect` authentication over HTTP `basic` auth

Thank you for offering a new example for OpenAPI!

It is widely understood that APIs should avoid HTTP Basic Auth, which is inherently insecure.
I recommend revising the Museum OpenAPI example to use a more secure security scheme.

use oauth2 security scheme (with authorizationCode flow and with specific read and write scopes -- scope names left to implementors) or openIdConnect security scheme
change the default security requirement to be a reference to that security scheme (not basic auth) and use a read scope
operations that require write access should not use the default security, but use an explicit operation-level security requirement with write or other scope.

Update Pull request templates

We're currently falling back to the organization default template which makes no sense in the context of this project. Update the template to be lightweight, but encourage users to say what they are changing and WHY so we can review.