jean-philippe
3fae2fcbe1
This is the initial commit for the CODEX_ADK project, a full-stack AI agent management platform featuring: BACKEND (ASP.NET Core 8.0): - CQRS architecture with 6 commands and 7 queries - 16 API endpoints (all working and tested) - PostgreSQL database with 5 entities - AES-256 encryption for API keys - FluentValidation on all commands - Rate limiting and CORS configured - OpenAPI/Swagger documentation - Docker Compose setup (PostgreSQL + Ollama) FRONTEND (Flutter 3.x): - Dark theme with Svrnty branding - Collapsible sidebar navigation - CQRS API client with Result<T> error handling - Type-safe endpoints from OpenAPI schema - Multi-platform support (Web, iOS, Android, macOS, Linux, Windows) DOCUMENTATION: - Comprehensive API reference - Architecture documentation - Development guidelines for Claude Code - API integration guides - context-claude.md project overview Status: Backend ready (Grade A-), Frontend integration pending 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
130 lines
3.1 KiB
Markdown
130 lines
3.1 KiB
Markdown
# 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
|