v2 (#161)

Author: jaspermayone

.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bundle exec rspec:*)",
+      "Bash(RAILS_ENV=test bundle exec rails:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

.github/workflows/update-api-docs.yml

@@ -0,0 +1,95 @@
+name: Update API Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'spec/requests/api/**'
+
+permissions:
+  contents: write
+
+env:
+  RAILS_ENV: test
+  CI: true
+
+jobs:
+  update-docs:
+    name: Generate and Update API Docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ssh-key: "${{ secrets.PUSH_KEY }}"
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: |
+          gem install bundler
+          bundle install
+          npm install
+
+      - name: Setup Database
+        env:
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test
+        run: |
+          bundle exec rails db:create
+          bundle exec rails db:schema:load
+
+      - name: Run API specs with OpenAPI generation
+        env:
+          OPENAPI: 1
+          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test
+          REDIS_URL: redis://localhost:6379/0
+        run: bundle exec rspec spec/requests/api --format progress
+
+      - name: Merge API Docs
+        if: hashFiles('doc/openapi*.yaml') != ''
+        run: bundle exec ./bin/merge-api-docs.rb
+
+      - name: Commit and push API Docs
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git add "doc/openapi.yaml"
+          git commit -m "Update API Documentation [skip ci]" || echo "No changes to commit"
+          git push origin main || echo "No changes to push"

.gitignore

@@ -42,3 +42,4 @@
 # Ignore key files for decrypting credentials and more.
 /config/credentials/*.key
 
+coverage

CLAUDE.md

@@ -30,6 +30,18 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `bundle exec rubocop -a` - Run linter with auto-fix
 - `bundle exec brakeman` - Run security vulnerability scanner
 
+### API Documentation
+- `OPENAPI=1 bundle exec rspec spec/requests/api` - Generate OpenAPI/Swagger documentation from request specs
+- Access docs at `/admin/api-docs` (requires admin login)
+- **Automatic generation**: GitHub Actions automatically updates docs when API specs change on `main` branch
+- **Configuration files**:
+  - `config/initializers/rspec_openapi.rb` - OpenAPI generation config
+  - `config/initializers/rswag_ui.rb` - Swagger UI config
+  - `config/initializers/rswag_api.rb` - API serving config
+- **Generated file**: `doc/openapi.yaml`
+- **Workflow**: `.github/workflows/update-api-docs.yml`
+- See `docs/api_documentation.md` for complete setup and usage
+
 ## Architecture Overview
 
 ### Core Purpose
@@ -134,6 +146,7 @@ A Rails 8 API backend that syncs college course schedules to Google Calendar wit
 7. **Template validation**: Calendar preference templates are validated; invalid syntax is rejected
 8. **OAuth token encryption**: All sensitive tokens are encrypted with Lockbox
 9. **Multi-email support**: Design features to support users with multiple connected Google accounts
+10. **API documentation auto-updates**: When modifying API endpoints, update request specs - docs regenerate automatically on `main` branch
 
 ## Common Development Workflows
 
@@ -163,8 +176,18 @@ A Rails 8 API backend that syncs college course schedules to Google Calendar wit
 4. Write RSpec tests in `spec/policies/` to verify permissions
 5. See `docs/authorization.md` for policy patterns
 
+### Adding/Updating API Endpoints
+1. Create/update controller action in `app/controllers/api/`
+2. Add request spec in `spec/requests/api/` - this generates the API docs
+3. Test locally: `OPENAPI=1 bundle exec rspec spec/requests/api`
+4. Check generated docs at `/admin/api-docs` (requires admin login)
+5. Docs auto-update on `main` branch via GitHub Actions
+6. To exclude specs from docs, add `openapi: false` to the describe block
+7. See `docs/api_documentation.md` for more details
+
 ### Running Tests for Specific Features
 - Authorization policies: `bundle exec rspec spec/policies/`
+- API endpoints: `bundle exec rspec spec/requests/api/` (or with `OPENAPI=1` to generate docs)
 - Calendar preferences: `bundle exec rspec spec/models/calendar_preference_spec.rb`
 - Template rendering: `bundle exec rspec spec/services/calendar_template_renderer_spec.rb`
 - Preference resolution: `bundle exec rspec spec/services/preference_resolver_spec.rb`

Gemfile

@@ -96,7 +96,7 @@ group :development, :test do
   gem "rubocop-rspec", "~> 3.8"
   gem "rubocop-rspec_rails", "~> 2.32"
   gem "query_count"
-  gem "bullet"
+  gem 'prosopite'
 end
 
 group :development do
@@ -116,6 +116,8 @@ group :test do
   # Use system testing [https://guides.rubyonrails.org/testing.html#system-testing]
   gem "capybara"
   gem "selenium-webdriver"
+  gem "rspec-openapi", "~> 0.20"
+  gem 'simplecov', require: false
 end
 
 gem "faraday", "~> 2.14"
@@ -134,5 +136,10 @@ gem "neighbor"
 gem "log_bench"
 
 gem "kaminari", "~> 1.2"
+gem "rswag-api", "~> 2.17.0"
+gem "rswag-ui", "~> 2.17.0"
+
+gem "pghero", "~> 3.7"
+gem "pg_query", ">= 2"
 
 gem "connection_pool", "~> 2.4"