CODEX_ADK/BACKEND/docs/README.md

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:

./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:

/// <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:

dotnet build

3. Export OpenAPI spec:

./export-openapi.sh

4. Update CHANGELOG.md if you made breaking changes

5. Commit everything together:

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):

# 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

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

Swagger UI

View API documentation locally:

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