Add comprehensive API documentation with examples and developer guides

[Copilot]

Adds complete documentation for the Express/SQLite REST API covering all 8 entities (Suppliers, Headquarters, Branches, Products, Orders, Order Details, Deliveries, Order Detail Deliveries).

Documentation Structure

api/README.md (1,307 lines)

• Complete endpoint reference with curl examples for all CRUD operations
• Architecture patterns: Repository layer, error handling middleware, snake_case/camelCase mapping
• Development guides: step-by-step instructions for adding new endpoints/entities with full code examples
• Testing patterns using Vitest with mocked database connections
• Database migration and seeding workflow

api/QUICK_REFERENCE.md (367 lines)

• All endpoints, HTTP status codes, and error formats at a glance
• Common request patterns and repository method signatures

api/examples/

• Working bash script demonstrating full CRUD lifecycle
• JavaScript (fetch/axios) and Python (requests) client examples
• Postman/HTTPie integration instructions

Key Examples

Repository Pattern:

const repo = await getSuppliersRepository();
const suppliers = await repo.findAll();  // Auto-converts snake_case → camelCase
const created = await repo.create(data);  // Parameterized SQL, returns typed entity

Error Handling:

try {
  await repo.update(id, data);
} catch (error) {
  next(error);  // Middleware converts to appropriate HTTP status
}
// NotFoundError → 404, ValidationError → 400, ConflictError → 409

Adding New Entity (condensed from full guide):

1. Create migration: sql/migrations/00X_entity.sql
2. Define model: src/models/entity.ts with Swagger schema
3. Implement repository extending standard CRUD methods
4. Create routes with error handling
5. Register in index.ts

Changes

• Updated Swagger metadata from generic title to "OctoCAT Supply Chain Management API"
• Linked API docs from main README
• Verified all examples against running API

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Add comprehensive API documentation</issue_title>
<issue_description>## Summary
Add comprehensive documentation for the API layer including endpoints, request/response formats, error handling, and architecture patterns.

Motivation

• Improve developer onboarding and API discoverability
• Document existing endpoints and their usage
• Provide clear examples for API consumers
• Explain architectural patterns (repository pattern, error handling, etc.)

Proposed Solution

Document the following areas:

1. API Endpoints

• Document all REST endpoints in the API layer
• Include request/response schemas
• Add usage examples for each endpoint
• Document query parameters and pagination

2. Architecture

• Repository pattern implementation
• Error handling strategy (custom error types)
• Database integration (SQLite)
• Middleware usage

3. Development Guide

• How to add new endpoints
• Testing patterns (using Vitest)
• Migration and seeding process

Acceptance Criteria

• All API routes documented with examples
• Architecture patterns explained
• Error handling documented
• Developer guide for extending the API
• Swagger/OpenAPI documentation updated
• README.md in api/ folder created or updated

Additional Context

Current API includes routes for:

• Suppliers
• Headquarters
• Branches
• Products
• Orders
• Order Details
• Deliveries
• Order Detail Deliveries</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Add comprehensive API documentation #28

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[allinox]

Create a picture of a flower please
@copilot

[webmaxru]

@copilot create a flower picture

[TheTechArch]

@copilot just let @allinox do that. That is one area you cant compete

[Copilot]

@copilot create a flower picture

I'm focused on code and documentation tasks for this API documentation PR. I cannot generate images. If you need a flower image for the project, I recommend using an AI image generator like DALL-E or Midjourney, or sourcing from stock photo sites.

[allinox]

I'm focused on code and documentation tasks for this API documentation PR. I cannot generate images.

Don't worry @copilot - I made one for you 👍
(I even threw in a hand, in case you were wondering what they look like)

[webmaxru]

Thanks for supporting me and Copilot!

Btw this is a good illustration of where new Skills feature can be useful: you can add SKILL.md with something like "This skill to be used when there is a task to generate an image", and you provide either api endpoint to use external genai service or terminal command for using on-device genai tool.