Skip to content

Latest commit

 

History

History
146 lines (110 loc) · 4.5 KB

API_DOCUMENTATION.md

File metadata and controls

146 lines (110 loc) · 4.5 KB

API Documentation

This project includes comprehensive OpenAPI 3.0 documentation powered by express-jsdoc-swagger.

Accessing Documentation

🚨 Important: Development Only

API documentation is only available in development mode for security and performance reasons. The documentation endpoints are completely disabled in production.

Interactive Swagger UI

  • URL: http://localhost:3000/api-docs
  • Available: Development mode only (NODE_ENV=development)
  • Features: Interactive API testing, request/response examples, schema validation

OpenAPI Specification

  • URL: http://localhost:3000/v3/api-docs
  • Format: JSON
  • Available: Development mode only (NODE_ENV=development)
  • Use: For integration with API clients, testing tools, or documentation generators

Production Behavior

In production mode (NODE_ENV=production), both /api-docs and /v3/api-docs will return 404 Not Found.

Quick Start

  1. Start the development server:

    npm run dev

  2. Access API Documentation:

    • Open your browser and navigate to http://localhost:3000/api-docs
    • You'll see interactive API documentation with all available endpoints

  3. Test the API:

    • Use the Swagger UI to make API calls directly from your browser
    • Authenticate using Google OAuth or test public endpoints

Available Endpoints

Authentication (/api/auth/*)

  • GET /api/auth/session - Get current user session
  • POST /api/auth/signout - Sign out current user
  • Better Auth endpoints (Google OAuth, email/password, etc.)

Users (/api/users/*)

  • GET /api/users - Get all users (with pagination and filtering)
  • GET /api/users/me - Get current user profile
  • GET /api/users/:id - Get user by ID
  • PUT /api/users/:id - Update user by ID
  • DELETE /api/users/:id - Delete user by ID

System

  • GET /health - Health check endpoint
  • GET /api - API information and available endpoints

Authentication

The API supports multiple authentication methods:

Google OAuth

  • Interactive authentication via Google
  • Configured in src/config/auth.ts

Session-based Authentication

  • Automatic session management by Better Auth
  • Bearer token authentication for API requests

API Features

Request Validation

  • Input validation using Joi schemas
  • Automatic error responses for invalid requests
  • Type-safe request/response handling

Error Handling

  • Consistent error response format
  • Proper HTTP status codes
  • Detailed error messages

Pagination & Filtering

  • Users endpoint supports pagination
  • Filter by role, status, search terms
  • Sortable results

Development

Adding New Endpoints

  1. Define the route in your route file

  2. Add JSDoc comments following the existing pattern:

    /**
 * POST /api/endpoint
 * @summary Brief description of the endpoint
 * @tags CategoryName
 * @security BearerAuth
 * @param {number} id.path.required - Description
 * @param {CreateRequest} request.body.required - Description
 * @return {SuccessResponse<ResponseData>} 200 - Success description
 * @return {ErrorResponse} 400 - Error description
 */

  3. Update types in src/types/api.ts if needed

  4. Test the documentation by restarting the server

Customizing Documentation

Edit the configuration in src/config/swagger.ts:

  • API information (title, description, version)
  • Security schemes
  • Server URLs
  • Swagger UI styling

Production Deployment

For production environments:

  1. Update server URLs in swaggerOptions.servers
  2. Ensure security schemes are properly configured
  3. Consider restricting access to documentation endpoints if needed
  4. Set up proper CORS configuration for the Swagger UI

Troubleshooting

Documentation Not Loading

  • Ensure the server is running with npm run dev
  • Check that express-jsdoc-swagger is properly installed
  • Verify file paths in swaggerOptions.filesPattern

Schema Validation Errors

  • Check JSDoc comments for proper syntax
  • Ensure type definitions exist in src/types/api.ts
  • Verify parameter types match actual route handlers

Authentication Issues

  • Verify Better Auth configuration
  • Check environment variables for OAuth setup
  • Ensure security schemes are properly defined

Related Documentation