# Codex API Documentation

This directory contains the API contract and documentation for the Codex API.

## Files

### openapi.json
**⚠️ AUTO-GENERATED - DO NOT EDIT MANUALLY**

The OpenAPI 3.0 specification for the Codex API. This file is the single source of truth for API contracts.

**To regenerate:**
```bash
./export-openapi.sh
```

This file should be regenerated whenever:
- New Commands or Queries are added
- Existing Commands/Queries are modified
- Request/response types change
- Authentication requirements change

### ARCHITECTURE.md
High-level design decisions, technology stack, and architectural patterns used in the Codex API.

Update this when:
- Major architectural changes occur
- New patterns or frameworks are adopted
- Infrastructure decisions are made

### CHANGELOG.md
**Breaking changes only** - tracks API contract changes that require client updates.

Update this when:
- Removing or renaming endpoints
- Changing request/response schemas in incompatible ways
- Modifying authentication requirements
- Any change that would break existing API clients

## Workflow

### For Backend Developers

1. **Add/modify Commands or Queries** with XML documentation:
```csharp
/// <summary>Describes what this query does</summary>
/// <param name="parameter">Parameter description</param>
/// <response code="200">Success response description</response>
public record MyQuery { }
```

2. **Build the solution** to generate XML documentation:
```bash
dotnet build
```

3. **Export OpenAPI spec**:
```bash
./export-openapi.sh
```

4. **Update CHANGELOG.md** if you made breaking changes

5. **Commit everything together**:
```bash
git add .
git commit -m "Add MyQuery endpoint with OpenAPI spec"
```

### For Frontend Developers

1. **Pull latest code** to get updated `docs/openapi.json`

2. **Generate client code** (optional):
```bash
# Example using openapi-generator
npx @openapitools/openapi-generator-cli generate \
  -i docs/openapi.json \
  -g typescript-fetch \
  -o src/api
```

3. **Check CHANGELOG.md** for breaking changes

## OpenAPI Spec Validation

The generated `openapi.json` includes:

- ✅ All endpoints with HTTP methods
- ✅ Complete request/response schemas
- ✅ XML documentation comments
- ✅ Authentication requirements (Bearer token)
- ✅ API versioning information
- ✅ Parameter descriptions
- ✅ Response codes

## CQRS Endpoint Conventions

OpenHarbor.CQRS auto-generates REST endpoints:

- **Commands**: `POST /api/command/{CommandName}`
- **Queries**: `POST /api/query/{QueryName}` or `GET /api/query/{QueryName}`
- **Dynamic Queries**: `POST /api/dynamicquery/{QueryItemType}`

Example:
- `HealthQuery` → `POST /api/query/health`
- `CreateUserCommand` → `POST /api/command/createuser`

## Tools

### OpenAPI Validators
```bash
# Validate OpenAPI spec
npx @apidevtools/swagger-cli validate docs/openapi.json
```

### Swagger UI
View API documentation locally:
```bash
dotnet run --project Codex.Api
# Open: http://localhost:5246/swagger
```

## Questions?

- **Architecture questions**: See `ARCHITECTURE.md`
- **Breaking changes**: See `CHANGELOG.md`
- **API contract**: See `openapi.json`
- **Code examples**: See `.claude-docs/` directory