API Documentation Automation

This page explains how API documentation is kept in sync with the CoquiTitle API codebase.

Overview

CoquiTitle API documentation is semi-automatically generated using:

1. Pydantic Models: Define request/response schemas in Python
2. OpenAPI Spec: Exported from Pydantic models to OpenAPI 3.1 JSON
3. Scalar: Renders the OpenAPI spec as an interactive API reference
4. GitHub Action: Syncs spec changes from alianza-hq to docs repo

Architecture

Source Files

File	Purpose
backend/coquititle/lambdas/api/src/models.py	Pydantic request/response models
backend/coquititle/lambdas/api/export_openapi.py	Script to generate OpenAPI spec
backend/coquititle/lambdas/api/openapi.json	Generated OpenAPI 3.1 specification
docs/static/openapi/coquititle.json	Copy of spec used by Scalar

Sync Workflow

When API code changes are merged to main in alianza-hq:

1. GitHub Action triggers (sync-api-docs.yml)
2. Python installs API dependencies
3. OpenAPI spec exported via export_openapi.py
4. PR created to docs repo with updated spec
5. Manual review and merge
6. Docs site deploys with updated API reference

Why Semi-Automatic?

The docs PR requires manual merge because:

• Allows review before publishing
• Catches any generation errors
• Maintains audit trail

Making API Changes

When you modify the CoquiTitle API:

1. Update Pydantic Models

Edit backend/coquititle/lambdas/api/src/models.py:

from pydantic import BaseModel, Field

class CreateCaseRequest(BaseModel):
    """Request body for creating a new case."""
    finca_id: str | None = Field(None, description="Property finca number")
    property_address: str | None = Field(None, description="Property address")

2. Regenerate OpenAPI Spec Locally

cd backend/coquititle/lambdas/api
python export_openapi.py

3. Preview Locally (Optional)

# Copy spec to docs
cp openapi.json /path/to/docs/static/openapi/coquititle.json

# Preview docs
cd /path/to/docs
npm start
# Visit http://localhost:3000/api/coquititle

4. Commit and Push

git add src/models.py
git commit -m "ALI-XXX: Add new field to CreateCaseRequest"
git push origin feature/ALI-XXX-new-field

5. After Merge

Once your PR is merged to main:

1. The sync workflow automatically runs
2. A PR appears in the docs repo
3. Review and merge the docs PR

Adding New Endpoints

When adding a new API endpoint:

1. Define the Pydantic model in models.py
2. Add the endpoint to index.py (use @app.route decorator)
3. Run tests to verify functionality
4. Export OpenAPI spec to update documentation

Example: Adding a New Endpoint

# models.py
class ArchiveCaseRequest(BaseModel):
    """Request body for archiving a case."""
    reason: str = Field(..., description="Reason for archiving")

class ArchiveCaseResponse(BaseModel):
    """Response for archive case endpoint."""
    case_id: str
    archived_at: datetime
    message: str

Scalar Theme Configuration

The Scalar API reference is configured in docusaurus.config.ts:

[
  '@scalar/docusaurus',
  {
    label: 'API Reference',
    route: '/api/coquititle',
    configuration: {
      spec: {
        url: '/openapi/coquititle.json',
      },
      hideModels: false,
      hideDownloadButton: false,
      darkMode: true,
      theme: 'kepler',
    },
  },
],

Troubleshooting

Spec Not Updating

1. Check GitHub Actions ran successfully
2. Verify the sync workflow was triggered
3. Check for any export script errors

Local Preview Issues

# Clear Docusaurus cache
npm run clear

# Reinstall dependencies
rm -rf node_modules
npm install

# Rebuild
npm run build

Missing Endpoints in Docs

Ensure your endpoint is decorated and has proper type hints:

@app.post("/coquititle/cases")
def create_case(body: CreateCaseRequest) -> CaseResponse:
    """Create a new title study case."""
    # Implementation...

GitHub Action Configuration

The sync workflow requires a DOCS_REPO_PAT secret in alianza-hq:

1. Create a Fine-grained PAT with:
   • contents: write on docs repo
   • pull_requests: write on docs repo
2. Add as DOCS_REPO_PAT secret in alianza-hq settings

Future Improvements

• Monorepo consolidation: Moving docs into alianza-hq would enable single-PR updates
• Auto-merge: Could auto-merge docs PRs if all checks pass
• Multi-API support: Extend pattern to other APIs (embargos, karibe, etc.)
• OpenAPI validation: Add schema validation in CI before generation