redocly / museum-openapi-example Goto Github PK

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

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

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)

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

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.

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.

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

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.

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.

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.