Learn OpenAPI from these Realistic Examples

For what felt like forever everyone was using the Pet Store as an example for OpenAPI and it never really made much sense. It was a bad API describing a weird problem badly, and these days it's even worse: it was based on OpenAPI v2.0 and vaguely updated, but in the world of OpenAPI v3.1 we need more realistic examples to use that leverage the amazing modern functionality and simplified syntax.

Whether you're just trying to learn how OpenAPI works in a more realistic domain than a pet shop, or you want to run some tooling you've built through a test suite using these examples, or you want to demonstrate to your team how their APIs could look in a new API Catalog(ue) you just built, these demonostration OpenAPI's can help you out.

Train Travel API, from Bump.sh

The wonderful folks over at Bump.sh sponsored my time to work on this OpenAPI description of a fictional European train travel API. It covers finding stations, trips, making bookings, paying for the tickets, and more. We're even working on an Arazzo workflow that will help demonstrate how to chain those requests and responses together.

It's open-source and available on GitHub, so use it for whatever (according to the Creative Commons license ofc) and send in any improvements you can think of.

Train Travel API: A Modern OpenAPI PetStore Replacement · Bump.sh

Everyone working with OpenAPI (formerly Swagger) will have come across the PetStore at some point. It’s a sample OpenAPI description for an imaginary Pet Store with an API, but the OpenAPI is old, and the API it describes is pretty far from best practices. We thought it was time for a refresh, so we’re bringing you the Train Travel API, a new sample OpenAPI you can use for your tooling and testing.

Use the following URL, or download it.

https://raw.githubusercontent.com/bump-sh-examples/train-travel-api/refs/heads/main/openapi.yaml

Museum API, from Redocly

This demo OpenAPI covers operation at a museum, with things like operational hours, managing events at the museum, and even returning QR codes. This helps showcase lots of OpenAPI v3.1 functionality, and also has an Arazzo document to help show off key workflows.

GitHub - Redocly/museum-openapi-example: An example OpenAPI description for an imaginary Museum API.

An example OpenAPI description for an imaginary Museum API. - GitHub - Redocly/museum-openapi-example: An example OpenAPI description for an imaginary Museum API.

GitHubRedocly

Use the following URL, or download it.

https://raw.githubusercontent.com/Redocly/museum-openapi-example/main/openapi.yaml

Galaxy API, from Scalar

The team over at Scalar have been hard at work on everything from JSON Schema reference parsers to amazing OpenAPI-based HTTP GUI Clients, and to test all that they've built an excellent sample API description that covers planets.

Ok so unless you work at Nasa this one is not the most realistic domain, but it covers loads of authentication methods and awkward things like uploading images in the HTTP Request body, which others do not.

scalar/packages/galaxy/README.md at main · scalar/scalar

Scalar is an open-source API platform: 🌐 Modern Rest API Client 📖 Beautiful API References…

GitHubscalar

Use the following URL, or download it.

 https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/3.1.yaml

Find more OpenAPI examples

If you need more examples of OpenAPI for any reason, there are loads over on the APIs.guru Marketplace. Most of these are real examples published by companies of all sizes, so you can see real world working OpenAPI descriptions.