Skip to content

Examples

This page helps you find the most useful runnable examples in the repository.

If you want to learn SpecStar by copying a working project instead of starting from a blank file, begin here.

If your first question is how to choose metadata, resource, blob, and queue backends, read the backend setup guide before picking a production-style example.

If you are new to the project, this is the suggested reading and running order:

  1. basic FastAPI example
  2. Pydantic-based example
  3. S3 storage example
  4. PostgreSQL + Disk + S3 blob production-style example
  5. RabbitMQ or Celery queue example

Example map

Example What it demonstrates Run command
Basic RPG API core CRUD setup, refs, search, GraphQL, blobs, migrations, custom actions uv run python examples/rpg_game_api.py
Pydantic RPG API using Pydantic models, validators, discriminated unions, GraphQL, blob support uv run python examples/rpg_game_pydantic_api.py
S3 backend example object storage for data and binary files, MinIO or AWS-style deployment uv run python examples/rpg_game_s3_api.py
PostgreSQL + S3 example production-oriented metadata queries in PostgreSQL; use it as a reference when your deployment prefers object storage for payloads and blobs uv run python examples/rpg_game_postgres_s3_api.py
Celery queue example worker-based background jobs; useful when your platform already uses Celery instead of the default RabbitMQ recommendation uv run python examples/rpg_game_celery_api.py

Which example should you choose?

Choose the basic RPG API if you want:

  • the fastest path to understanding SpecStar
  • a broad overview of features in one file
  • an example that matches the main documentation flow

Choose the Pydantic example if you already use:

  • BaseModel
  • field validators
  • discriminated unions
  • Pydantic-first application design

Choose the S3 or PostgreSQL + S3 examples if you need:

  • persistent storage
  • production-like deployment patterns
  • blob and binary file workflows
  • object storage or MinIO compatibility

Choose the Celery example if you need:

  • worker-based background jobs
  • retry and queue patterns
  • asynchronous event processing

After starting an example

Most examples expose a FastAPI application, so the next step is usually to open:

  • http://localhost:8000/docs

Then compare what you see with these guides: