Cursor rule

1---
2description: API endpoint consistency — checklist to run after every API endpoint commit (Minitest behavior, rswag docs-only, API key auth).
3globs: app/controllers/api/v1/**/*.rb, spec/requests/api/v1/**/*.rb, test/controllers/api/v1/**/*.rb
4alwaysApply: false
5---
6 
7# API endpoint consistency (post-commit checklist)
8 
9When adding or modifying API v1 endpoints, ensure the following so behavior, docs, and auth stay consistent.
10 
11## 1. Minitest behavioral coverage
12 
13- **Location**: `test/controllers/api/v1/{resource}_controller_test.rb`
14- **Scope**: All new or changed actions must have Minitest coverage here. Do not rely on rswag specs for behavioral assertions.
15- **Pattern**:
16  - Use `ApiKey.create!` (read and read_write scopes) and `api_headers(api_key)` → `{ "X-Api-Key" => api_key.display_key }`. Do not use OAuth/Bearer in these tests.
17  - Cover: index/show (and create/update/destroy for write endpoints), read-only key blocking writes (403), invalid params (422), invalid date (422), not found (404), missing auth (401).
18  - Follow existing API v1 test style: see [valuations_controller_test.rb](mdc:test/controllers/api/v1/valuations_controller_test.rb) and [transactions_controller_test.rb](mdc:test/controllers/api/v1/transactions_controller_test.rb).
19 
20## 2. rswag is docs-only
21 
22- **Location**: `spec/requests/api/v1/{resource}_spec.rb`
23- **Rule**: These specs exist only for OpenAPI generation. Do not add `expect(...)` or `assert_*` (or any behavioral assertions). Use `run_test!` without custom assertion blocks so the spec only documents request/response and regenerates `docs/api/openapi.yaml`.
24- **Regenerate**: After edits, run `RAILS_ENV=test bundle exec rake rswag:specs:swaggerize`.
25 
26## 3. Same API key auth in all rswag specs
27 
28- **Rule**: Every request spec in `spec/requests/api/v1/` must use the same API key auth pattern so generated docs are consistent.
29- **Pattern** (match holdings_spec, trades_spec, transactions_spec, etc.):
30 
31```ruby
32  let(:api_key) do
33    key = ApiKey.generate_secure_key
34    ApiKey.create!(
35      user: user,
36      name: 'API Docs Key',
37      key: key,
38      scopes: %w[read_write],
39      source: 'web'
40    )
41  end
42 
43  let(:'X-Api-Key') { api_key.plain_key }
44```
45 
46- Do not use Doorkeeper/OAuth in these specs (no `Doorkeeper::Application`, `Doorkeeper::AccessToken`, or `Authorization: "Bearer ..."`). Use API key only. Note: [valuations_spec.rb](mdc:spec/requests/api/v1/valuations_spec.rb) currently uses OAuth; update it to the API key pattern above when editing that file.
47