Add OpenAPI 3.1 specification and Scalar UI documentation

[Copilot]

• Install required dependencies (@scalar/nextjs-api-reference@latest, @redocly/cli)
• Create OpenAPI specification file at public/api-docs/openapi.yaml
• Document all API endpoints (auth/save-token, cron/sync, health)
• Create health check endpoint at src/app/api/health/route.ts
• Create API documentation page at src/app/api-docs/route.ts
• Update package.json with docs:validate script
• Validate OpenAPI spec with @redocly/cli (passed with 2 acceptable warnings)
• Address code review feedback (improved version reading in health endpoint)
• Run security checks with CodeQL (0 vulnerabilities found)
• Address PR review comments:
  • Health endpoint now supports APP_VERSION env var with fallback to package.json
  • Auth endpoint 401 responses now return JSON instead of plain text
  • Sync endpoint "No eligible users" response now matches schema with all required fields
  • Added APP_VERSION=1.0.1 to .example.env for universal version management

Original prompt

🎯 Objective

Add comprehensive API documentation for all internal endpoints using OpenAPI 3.1 specification and Scalar UI (modern alternative to Swagger UI). This improves developer experience, enables API testing directly from the browser, and provides clear documentation for authentication, rate limiting, and error handling.

---

📋 Requirements

1. Create OpenAPI Specification

File: public/api-docs/openapi.yaml

Create a complete OpenAPI 3.1 specification documenting all internal API endpoints:

Endpoints to Document:

1. Authentication:

   • POST /api/auth/save-token - Save EzyGo authentication token

2. Sync:

   • GET /api/cron/sync - Sync attendance data with EzyGo (supports both cron jobs and authenticated users)

3. Contact:

   • POST /api/contact (if exists as API route, otherwise document the server action pattern)

4. Health:

   • GET /api/health - Health check endpoint (needs to be created)

Requirements for Each Endpoint:

• ✅ Complete path definition
• ✅ HTTP method
• ✅ Request body schema with validation rules (min/max length, patterns, required fields)
• ✅ All possible response codes (200, 400, 401, 429, 500)
• ✅ Response schemas with examples
• ✅ Query parameters (for /api/cron/sync?username=)
• ✅ Authentication requirements
• ✅ Rate limiting information
• ✅ Detailed descriptions

Schema Components:

• Error - Standard error response
• ValidationError - Validation error with field-level details
• RateLimitError - Rate limit exceeded error

Security Schemes:

• BearerAuth - For CRON_SECRET (cron jobs)
• SupabaseAuth - For session cookies (authenticated users)

Metadata:

• Title: "GhostClass API"
• Version: "1.0.0"
• Description: Include authentication guide, rate limits, base URLs
• Contact: email, GitHub URL
• License: MIT
• Servers: Production and development URLs

---

2. Create API Documentation Page

File: src/app/api-docs/page.tsx

• Use @scalar/nextjs-api-reference for modern, interactive API docs
• Configure with:
  • Theme: purple (matches GhostClass branding)
  • Layout: modern
  • Dark mode: enabled by default
  • Show sidebar: true
  • Default expand all tags: true
  • Authentication: prefer SupabaseAuth
• Add metadata:
  • Title: "API Documentation | GhostClass"
  • robots: noindex, nofollow (don't index internal docs)
• Use dynamic import to avoid SSR issues

---

3. Create Health Check Endpoint

File: src/app/api/health/route.ts

Simple health check endpoint that returns:

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-01-24T12:00:00Z"
}

• Use Next.js App Router convention
• Return JSON with NextResponse
• Include package version from environment if available
• Always return 200 status

---

4. Install Required Dependencies

Add to package.json:

{
  "dependencies": {
    "@scalar/nextjs-api-reference": "^0.3.0"
  },
  "devDependencies": {
    "@redocly/cli": "^1.10.0"
  },
  "scripts": {
    "docs:validate": "npx @redocly/cli lint public/api-docs/openapi.yaml"
  }
}

---

5. Update Navigation (Optional Enhancement)

If there's a developer/admin section in the navbar, add a link:

<Link href="/api-docs" target="_blank">
  API Docs
</Link>

Note: Only add if there's an appropriate place in existing navigation. Don't create new navigation structure.

---

🎨 OpenAPI Specification Requirements

Structure:

openapi: 3.1.0
info:
  title: GhostClass API
  version: 1.0.0
  description: |
    Multi-line description with:
    - Authentication guide
    - Rate limiting info
    - Base URLs
  contact:
    name: GhostClass Support
    email: contact@ghostclass.devakesu.com
  license:
    name: MIT

servers:
  - url: https://ghostclass.devakesu.com
    description: Production
  - url: http://localhost:3000
    description: Development

tags:
  - name: Authentication
  - name: Sync
  - name: Contact
  - name: Health

paths:
  # Document each endpoint here

components:
  schemas:
    # Define reusable schemas
  securitySchemes:
    # Define auth methods

externalDocs:
  description: GitHub Repository
  url: https://github.com/devakesu/GhostClass

Example Endpoint Documentation:

/api/auth/save-token:
  post:
    tags:
      - Authentication
    summary: Save EzyGo authentication token
    description: |
      Detailed multi-line description
      - What it does
      - Rate limits
      - Authentication requirements
    operationId: saveAuthToken
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - token
            properties:
              token:
                type: string
                minLength: 20
                maxLength: 2000
                description: EzyGo JWT token
          examples:
            validToken:
              summary: Valid token example
            ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/devakesu/GhostClass/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR introduces internal API documentation using an OpenAPI 3.1 spec plus a Scalar-powered interactive UI, and adds a simple health check endpoint and related tooling. It focuses on documenting existing auth/sync endpoints, wiring up a browsable /api-docs route, and validating the spec with Redocly.

Changes:

• Added a /api/health endpoint returning a simple JSON health status with app version and timestamp.
• Introduced a /api-docs route using @scalar/nextjs-api-reference to render interactive API docs backed by public/api-docs/openapi.yaml.
• Created an OpenAPI 3.1 specification for POST /api/auth/save-token, GET /api/cron/sync, and GET /api/health, and wired up @redocly/cli plus a docs:validate npm script; updated dependencies/lockfile accordingly.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/app/api/health/route.ts	Adds a dynamic health check route returning status, version, and timestamp for monitoring and uptime checks.
src/app/api-docs/route.ts	Exposes the Scalar API reference UI at /api-docs, configured to load the OpenAPI spec from /api-docs/openapi.yaml with the desired theme and layout.
public/api-docs/openapi.yaml	Defines the OpenAPI 3.1 spec, including metadata, security schemes, shared error schemas, and detailed documentation for the auth, sync, and health endpoints.
package.json	Adds @scalar/nextjs-api-reference and @redocly/cli dependencies and a docs:validate script to lint the OpenAPI spec.
package-lock.json	Updates the lockfile to pin all new transitive dependencies introduced by Scalar and Redocly tooling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• otel.cloud.redocly.com
  • Triggering command: /usr/local/bin/node node /home/REDACTED/.npm/_npx/1738445911c9ab26/node_modules/.bin/redocly lint public/api-docs/openapi.yaml (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

@devakesu Unfortunately I hit an unexpected error while processing your comment. I've automatically reported this to GitHub.

You can ask me to try again later by mentioning me in a new comment.

If you want to contact GitHub about this error, please mention the following identifier so they can better serve you: 4e81cc86-5b54-4119-b30a-a4b953a3bdb9

Sorry for the inconvenience!

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• otel.cloud.redocly.com
  • Triggering command: /usr/local/bin/node node /home/REDACTED/.npm/_npx/1738445911c9ab26/node_modules/.bin/redocly lint public/api-docs/openapi.yaml (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[devakesu]

@copilot Unable to merge, commits by you are unverified.

[Copilot]

@copilot Unable to merge, commits by you are unverified.

I don't have access to GPG keys to sign commits in this environment. The commits are made through the report_progress tool which doesn't support commit signing.

To resolve this, you have two options:

1. Disable the "require signed commits" branch protection rule temporarily for this PR, or
2. Manually sign the commits yourself:

   git checkout copilot/add-openapi-documentation
   git rebase --exec 'git commit --amend --no-edit -n -S' -i HEAD~8
   git push --force-with-lease

Alternatively, you can squash and merge the PR, which will create a new signed commit when you merge it through GitHub's UI (if you have commit signing enabled on your account).