This API exists to help people learn OpenAPI by describing a realistic API in a realistic way.

The world of OpenAPI has been plagued by "The Pet Store", an old API description used as a demo in every project ever. It describes a RPC-esque API that's mascerading as REST, and describes it poorly, using old OpenAPI 2.0 which has been upgraded to OpenAPI v3.0 without taking advantage of any of the new features.

This example API has been written by somebody who uses OpenAPI every day, and has described 100s of APIs.

Instead of shying away of tough decisions, this OpenAPI gets stuck into advanced topics like:

• How to split files up with $ref to avoid repeating ourselves.
• How to reuse the same model for read and write operations.
• How to wrap data with a wrapper like { data: [], links: {} }.

This might not be the easiest API description to read in a text editor, but it looks wonderful when put through Bump.sh.

Preview this OpenAPI on Bump.sh

Or download it yourself and have a poke around.

cd server
PORT=8086 npm run start

npx @redocly/cli lint openapi.yaml

npx @redocly/cli bundle ./openapi.yaml --dereferenced --output ./openapi.json

npx @redocly/cli build-docs openapi.yaml --output=openapi-redoc-static.html

The contents of this repository are licensed under CC BY-NC-SA 4.0.