Skip to content

Sample OpenAPI description to use for whatever you like, as a hopefully more modern and useful alternative to the Petstore.

Notifications You must be signed in to change notification settings

bump-sh-examples/train-travel-api

Repository files navigation

Train Travel API

This API does not exist, but exists to help people learn OpenAPI by describing a realistic API in a realistic way.

Background

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.

Goals

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.

License

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

About

Sample OpenAPI description to use for whatever you like, as a hopefully more modern and useful alternative to the Petstore.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published