Quirky NPC Service 🎲

An API-only Ruby on Rails app that generates and manages silly, Dungeons & Dragons-inspired NPCs with quirky names, jobs, moods, and traits.

🧠 Perfect for D&D game masters, fantasy writers, or anyone who enjoys a good goblin joke.

---

🚀 Features

• Generate fully procedural NPCs (POST /npcs/generate)
• Save, update, delete, and list NPCs
• Random NPC endpoint (GET /npcs/random)
• Filtering by species and alignment
• Pagination with Pagy
• Friendly JSON error handling
• Auto-generated API documentation via Swagger (Rswag)
• JSON responses with ActiveModelSerializers

---

📘 API Documentation

🔗 Explore the API: https://quirky-npc-service.onrender.com/api-docs/index.html

The Swagger UI provides a live, interactive interface to test and understand all available endpoints of the Quirky NPC Service.

🔍 What’s Included:

• All available endpoints, grouped by feature (e.g., NPC management, random generation)
• Request & response examples for common use cases
• Error responses and validation details (400, 404, 422, 429)
• Filterable parameters like species, alignment, mood, job, and quirk
• Response schemas with real example NPCs and pagination metadata
• Enum value listings for structured fields (e.g., all D&D alignments)
• Optional: Rate limit documentation (if enabled via Rack::Attack)

🧪 Try it Out

You can make real requests directly from the docs — great for testing your frontend integration or exploring available features.

---

📊 Test Coverage

We use SimpleCov to track test coverage.

By default, coverage is not generated on every run.

To generate a report manually:

COVERAGE=true bundle exec rspec

---

🧙‍♂️ Example: Generated NPC

{
  "name": "Tilda Fizzlepot",
  "job": "Potion Tester",
  "quirk": "Only speaks in rhymes",
  "mood": "Suspiciously friendly",
  "species": "Gnome",
  "alignment": "Chaotic Neutral"
}

✅ Tests

• ✅ Model validations and methods (Npc)
• ✅ NPC generator service (NpcGeneratorService)
• ✅ Serializer output (NpcSerializer)
• ✅ Full request/integration specs using rswag
• ✅ Global error handling:
  • 404 – Record not found
  • 400 – Missing required parameters
  • 422 – Invalid filter values

🪄 License

MIT — use freely, modify gleefully, and enjoy the chaos 🐉