GitHubEmailContact
Skip to main content

CLI Commands Reference

The django_client module provides powerful management commands for generating API clients and validating OpenAPI schema quality.

Commands Overview​

CommandPurposeKey Features
generate_clientGenerate TypeScript and Python clientsMulti-group generation, dry-run, interactive mode
validate_openapiValidate and fix OpenAPI schema qualityAuto-fix issues, detailed reports, rule-based validation

generate_client​

Generate type-safe TypeScript and Python API clients from your Django REST Framework API.

Basic Usage​

# Generate all configured groups
python manage.py generate_client

# Generate specific groups
python manage.py generate_client --groups core billing

# Generate Python only
python manage.py generate_client --python

# Generate TypeScript only
python manage.py generate_client --typescript

Command Options​

Generation Options​

--groups [GROUP ...]

  • Generate specific groups only
  • Default: all configured groups
python manage.py generate_client --groups core custom

--python

  • Generate Python client only (skip TypeScript)
python manage.py generate_client --python

--typescript

  • Generate TypeScript client only (skip Python)
python manage.py generate_client --typescript

--no-python

  • Skip Python client generation
python manage.py generate_client --no-python

--no-typescript

  • Skip TypeScript client generation
python manage.py generate_client --no-typescript

Utility Options​

--dry-run

  • Validate configuration without generating files
  • Shows what will be generated
python manage.py generate_client --dry-run

--list-groups

  • List all configured groups and exit
  • Shows group details and matched apps
python manage.py generate_client --list-groups

--validate

  • Validate configuration and show statistics
python manage.py generate_client --validate

--interactive / -i

  • Run in interactive mode with prompts
  • Requires click package
python manage.py generate_client --interactive

Examples​

Generate all configured groups:

python manage.py generate_client

Output:

Generating clients for 2 group(s):

  • core (Core API)
  • billing (Billing API)

Languages:
  → Python
  → TypeScript

============================================================

📦 Processing group: core
  Apps: users, accounts, profiles
  → Generating OpenAPI schema...
  ✅ Schema saved: openapi/schemas/core.json
  → Parsing to IR...
  ✅ Parsed: 15 schemas, 42 operations
  → Generating Python client...
  ✅ Python client: openapi/clients/python/core (38 files)
  → Generating TypeScript client...
  ✅ TypeScript client: openapi/clients/typescript/core (52 files)
  → Archiving...
  ✅ Archived: openapi/archive/core_2025-01-15_14-30-00.zip

📦 Processing group: billing
  Apps: payments, subscriptions
  → Generating OpenAPI schema...
  ✅ Schema saved: openapi/schemas/billing.json
  → Parsing to IR...
  ✅ Parsed: 8 schemas, 24 operations
  → Generating Python client...
  ✅ Python client: openapi/clients/python/billing (22 files)
  → Generating TypeScript client...
  ✅ TypeScript client: openapi/clients/typescript/billing (31 files)
  → Archiving...
  ✅ Archived: openapi/archive/billing_2025-01-15_14-30-15.zip

============================================================

✅ Successfully generated clients for 2 group(s)!

Output directory: /path/to/project/openapi
  Python:     openapi/clients/python
  TypeScript: openapi/clients/typescript

Workflow Integration​

Pre-Deployment Script​

#!/bin/bash
# scripts/generate_clients.sh

set -e

echo "🚀 Generating API clients..."
python manage.py generate_client

echo "✅ Validating TypeScript..."
cd frontend && pnpm tsc --noEmit

echo "✅ Validating Python..."
cd ../backend && mypy api_client/

echo "🎉 Clients generated and validated!"

GitHub Actions​

name: Generate API Clients

on:
  push:
    paths:
      - 'api/**'
      - '**/serializers.py'
      - '**/views.py'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Generate clients
        run: python manage.py generate_client

      - name: Commit changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add openapi/
          git commit -m "chore: update API clients [skip ci]" || true
          git push

Docker Build​

FROM python:3.12

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

# Generate clients during build
RUN python manage.py generate_client

CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

validate_openapi​

Validate and auto-fix OpenAPI schema quality issues in Django REST Framework serializers.

Why Validation Matters​

Poor OpenAPI schema quality causes:

  • ❌ Missing type hints → Any types in generated clients
  • ❌ Missing help text → No documentation in generated code
  • ❌ Ambiguous field types → Runtime errors
  • ❌ Missing read_only → Write attempts on read-only fields

The validator finds and fixes these issues automatically.

Basic Usage​

# Check all serializers
python manage.py validate_openapi

# Check specific app
python manage.py validate_openapi --app users

# Auto-fix issues
python manage.py validate_openapi --fix

# Preview fixes without applying
python manage.py validate_openapi --fix --dry-run

# Generate HTML report
python manage.py validate_openapi --report html

Command Options​

Scope Options​

--app APP_NAME

  • Check specific Django app only
python manage.py validate_openapi --app accounts

--file PATH

  • Check specific file only
python manage.py validate_openapi --file users/serializers.py

--pattern PATTERN

  • File pattern to match (default: *serializers.py)
python manage.py validate_openapi --pattern "*api.py"

Action Options​

--fix

  • Apply auto-fixes to issues
python manage.py validate_openapi --fix

--dry-run

  • Preview fixes without applying changes
python manage.py validate_openapi --fix --dry-run

--no-confirm

  • Skip confirmation prompts when fixing
python manage.py validate_openapi --fix --no-confirm

Reporting Options​

--report {console,json,html}

  • Report format (default: console)
python manage.py validate_openapi --report html

--output PATH

  • Output file for JSON/HTML reports
python manage.py validate_openapi --report html --output report.html

--summary

  • Show summary only (compact output)
python manage.py validate_openapi --summary

Filtering Options​

--severity {error,warning,info}

  • Filter by minimum severity level
python manage.py validate_openapi --severity error

--rule RULE_ID

  • Check specific rule only
python manage.py validate_openapi --rule type-hint-001

--fixable-only

  • Show only auto-fixable issues
python manage.py validate_openapi --fixable-only

Utility Options​

--list-rules

  • List all validation rules and exit
python manage.py validate_openapi --list-rules

--verbose

  • Show detailed output
python manage.py validate_openapi --verbose

Validation Rules​

Common validation rules include:

Rule IDNameSeverityAuto-Fixable
type-hint-001Missing type hintsErrorYes
help-text-001Missing help_textWarningNo
read-only-001Missing read_onlyWarningYes
default-001Missing default valuesInfoNo
max-length-001Missing max_lengthWarningYes

View all rules:

python manage.py validate_openapi --list-rules

Examples​

Check all serializers:

python manage.py validate_openapi

Output:

🔍 Scanning for issues...

Found 12 issues in 5 files:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
users/serializers.py
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Line 15: UserSerializer.email
  ❌ ERROR [type-hint-001] Missing type hint
    → Add type hint: email: str = serializers.EmailField(...)
    ✅ Auto-fixable

  Line 18: UserSerializer.bio
  ⚠️  WARNING [help-text-001] Missing help_text
    → Add: help_text="User biography"

  Line 22: UserSerializer.created_at
  ⚠️  WARNING [read-only-001] Missing read_only=True
    → Add: read_only=True
    ✅ Auto-fixable

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
accounts/serializers.py
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Line 30: AccountSerializer.balance
  ❌ ERROR [type-hint-001] Missing type hint
    → Add type hint: balance: Decimal = serializers.DecimalField(...)
    ✅ Auto-fixable

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Summary:
  • Total issues: 12
  • Errors: 5
  • Warnings: 6
  • Info: 1
  • Auto-fixable: 8

💡 Tip: Run with --fix to auto-fix 8 issue(s)

Workflow Integration​

Pre-Commit Hook​

#!/bin/bash
# .git/hooks/pre-commit

echo "🔍 Validating OpenAPI schemas..."

# Check only staged files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep "serializers.py$")

if [ -n "$STAGED_FILES" ]; then
    for file in $STAGED_FILES; do
        python manage.py validate_openapi --file "$file" --severity error
        if [ $? -ne 0 ]; then
            echo "❌ Validation failed for $file"
            echo "💡 Run: python manage.py validate_openapi --file $file --fix"
            exit 1
        fi
    done
fi

echo "✅ All schemas valid"

CI/CD Pipeline​

name: Validate OpenAPI Schemas

on:
  pull_request:
    paths:
      - '**/*serializers.py'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Validate schemas
        run: |
          python manage.py validate_openapi --severity error
          python manage.py validate_openapi --report html --output report.html

      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: validation-report
          path: report.html

Weekly Report​

#!/bin/bash
# scripts/weekly_validation.sh

# Generate comprehensive report
python manage.py validate_openapi \
  --report html \
  --output "reports/validation_$(date +%Y-%m-%d).html"

# Send to team (example with curl)
curl -X POST https://your-webhook.com/reports \
  -F "file=@reports/validation_$(date +%Y-%m-%d).html"

Common Workflows​

Development Workflow​

During active development:

# 1. Validate configuration
python manage.py generate_client --validate

# 2. List groups and check matched apps
python manage.py generate_client --list-groups

# 3. Validate OpenAPI quality
python manage.py validate_openapi --app myapp

# 4. Fix issues
python manage.py validate_openapi --app myapp --fix

# 5. Generate clients
python manage.py generate_client

Pre-Deployment Checklist​

Before deploying to production:

# 1. Validate everything
python manage.py validate_openapi --severity error

# 2. Generate fresh clients
python manage.py generate_client

# 3. Run type checks
cd frontend && pnpm tsc --noEmit
cd ../backend && mypy api_client/

# 4. Commit changes
git add openapi/
git commit -m "chore: update API clients"

Debugging Issues​

When generation fails:

# 1. Check configuration
python manage.py generate_client --validate

# 2. List groups
python manage.py generate_client --list-groups

# 3. Dry run to see what would happen
python manage.py generate_client --dry-run

# 4. Validate schemas
python manage.py validate_openapi --verbose

# 5. Generate specific group
python manage.py generate_client --groups problematic_group

Troubleshooting​

generate_client Issues​

"OpenAPI client generation is not enabled"

# Enable in django-cfg configuration
openapi_client: OpenAPIClientConfig = OpenAPIClientConfig(
    enabled=True,  # ← Must be True
    # ...
)

"No groups to generate"

  • Check that groups are configured
  • Run --list-groups to see matched apps
  • Verify app names match installed apps

"No apps matched for group"

  • Check app name patterns in group configuration
  • Run --list-groups to see matched apps
  • Verify apps are in INSTALLED_APPS

validate_openapi Issues​

"No issues found" but clients have any types

  • Check that serializers have type hints
  • Run with --verbose flag
  • Verify correct serializer file pattern

"Auto-fix failed"

  • Run with --dry-run to preview changes
  • Check file permissions
  • Review error messages with --verbose

Best Practices​

1. Run Validation Before Generation​

Always validate schemas before generating clients:

python manage.py validate_openapi --severity error --fix
python manage.py generate_client

2. Use Dry Run for Testing​

Test configuration changes with dry-run:

python manage.py generate_client --dry-run

3. Generate Regularly​

Regenerate clients after any API changes:

# After modifying serializers
python manage.py generate_client

4. Version Control Clients​

Always commit generated clients:

git add openapi/
git commit -m "chore: update API clients"

5. CI/CD Integration​

Automate generation in your CI/CD pipeline (see workflow examples above).

Next Steps​

Last updated on