Add Scalar API reference

AGENTS.md

@@ -0,0 +1,31 @@
+# AGENTS.md
+
+## Stack
+- Single Rails API app.
+- Use Ruby `3.1.2` (`.ruby-version`) and Bundler `2.5.22` (`Gemfile.lock`). macOS system Ruby/Bundler fails here before the app boots; switch to the project Ruby first.
+- Prefer project binstubs (`bin/rails`, `bin/rake`) once the correct Ruby is active.
+- There is no repo-local lint/typecheck toolchain to run; verification is Rails commands plus RSpec.
+
+## Setup
+- `bin/setup` is the canonical bootstrap, but it assumes `config/database.yml` already exists. That file is not checked in.
+- PostgreSQL is the only DB (`pg` gem; `db/schema.rb` enables `plpgsql`). After schema changes, use `bin/rails db:prepare`.
+- Focused test run: `bundle exec rspec spec/path/to/file_spec.rb`.
+
+## Data Loading
+- `bundle exec rake hp_data:build` imports `public/data/data.xlsx` into `Genre`, `School`, `SchoolHouse`, `Person`, and `Creature`.
+- That importer skips each table if it already has rows, so rerunning it does not refresh existing data.
+- `bin/rails db:seed` separately loads `db/seeds/*.rb` in lexical order (`001_...`, `002_...`). Keep filenames ordered if you add new seed files.
+
+## Code Map
+- Trust `config/routes.rb` over the README: the README endpoint list is stale.
+- API entrypoints live in `app/controllers/api/v1`.
+- All JSON rendering goes through `app/controllers/concerns/response.rb`; shared API error handling lives in `app/controllers/concerns/exceptions.rb`.
+- Response payloads are defined in `app/serializers/*` with `JSONAPI::Serializer`; controller/model changes often require serializer updates too.
+- Scalar docs live at `public/docs/index.html` and load `public/openapi.yaml`; keep that spec in sync with routes, serializers, and shared error responses.
+- Current domain models are `School`, `SchoolHouse`, `Genre`, `Person`, and `Creature`. There is no current `Wizard` or `Student` model in `app/models`.
+
+## Gotchas
+- "Students" are derived from `Person.students`, which filters the misspelled `ocupation` column. Do not rename or "fix" that spelling without a real migration and data update.
+- `config/routes.rb` already marks the nested `people/students` route as broken. If you touch student endpoints, update routes, docs, and specs together.
+- Many request/model specs are stale scaffold leftovers or still reference removed `Wizard`/`Student` resources. Validate behavior against routes/models before trusting those specs.
+- The only GitHub Actions workflow is a tag-triggered release. It is not a reliable safety net right now: the test step is commented out, and the Postgres service password does not match the workflow `DATABASE_URL` password.

README.md

@@ -19,7 +19,7 @@
 **A RESTful OPEN API for the Wizarding World.**  
 Access data about characters, creatures, schools, and houses through a simple JSON interface.
 
-[View Documentation](#-documentation) • [Report Bug](https://github.com/CarlosLeonCode/harry_potter_open_api/issues) • [Request Feature](https://github.com/CarlosLeonCode/harry_potter_open_api/issues)
+[View Documentation](https://harry-potter-open-api-ff4c7a51ed23.herokuapp.com/docs) • [Report Bug](https://github.com/CarlosLeonCode/harry_potter_open_api/issues) • [Request Feature](https://github.com/CarlosLeonCode/harry_potter_open_api/issues)
 
 </div>
 
@@ -32,18 +32,12 @@ Access data about characters, creatures, schools, and houses through a simple JS
 https://harry-potter-open-api-ff4c7a51ed23.herokuapp.com
 ```
 
-### Endpoints
+### Interactive Reference
 
-| Resource | Method | Endpoint | Description |
-| :--- | :---: | :--- | :--- |
-| **Schools** | `GET` | `/api/v1/schools` | List all wizarding schools |
-| **Houses** | `GET` | `/api/v1/school_houses` | List all school houses |
-| **House Details** | `GET` | `/api/v1/school_houses/:id` | Get a specific house by ID |
-| **Characters** | `GET` | `/api/v1/people` | List all characters |
-| **Character Details** | `GET` | `/api/v1/people/:id` | Get a specific character by ID |
-| **Students** | `GET` | `/api/v1/people/students` | List only students |
-| **Creatures** | `GET` | `/api/v1/creatures` | List all magical creatures |
-| **Creature Details** | `GET` | `/api/v1/creatures/:id` | Get a specific creature by ID |
+- Browse the API in Scalar at [`/docs`](https://harry-potter-open-api-ff4c7a51ed23.herokuapp.com/docs).
+- The OpenAPI source served by the app is available at [`/openapi.yaml`](https://harry-potter-open-api-ff4c7a51ed23.herokuapp.com/openapi.yaml).
+- The checked-in OpenAPI file is now the documentation source of truth, alongside `config/routes.rb`.
+- Student routes are intentionally excluded from the current docs because the nested route is marked broken in `config/routes.rb` and there is no matching `StudentsController` implementation in `app/controllers/api/v1`.
 
 <br />
 
@@ -106,6 +100,8 @@ rails s
 ```
 Access the API at `http://localhost:3000/api/v1/...`
 
+Docs are available locally at `http://localhost:3000/docs`.
+
 </details>
 
 <br>

config/routes.rb

@@ -1,5 +1,7 @@
 Rails.application.routes.draw do
 
+  get '/docs', to: redirect('/docs/index.html')
+
   root to: redirect('https://harrypotter-open-api.netlify.app/')
 
   # -- Start api v1 routes

public/docs/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Harry Potter Open API Docs</title>
+    <style>
+      html,
+      body,
+      #app {
+        height: 100%;
+        margin: 0;
+      }
+
+      body {
+        background: #0b1020;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+    <script>
+      Scalar.createApiReference('#app', {
+        url: '/openapi.yaml',
+      })
+    </script>
+  </body>
+</html>