Skip to main content

CODITECT License Management API - Documentation Guide

This directory contains comprehensive API documentation for the CODITECT License Management API.

Documentation Files​

1. api-documentation.md​

Complete API reference documentation including:

  • Authentication guide (Firebase JWT)
  • All endpoint specifications with request/response examples
  • Error handling documentation
  • Rate limiting information
  • Client integration examples (Python, JavaScript)
  • Complete session lifecycle workflows

Target Audience: Developers integrating with the API

Format: Markdown

2. OpenAPI Schema (openapi-schema.yaml)​

Machine-readable API specification in OpenAPI 3.0 format.

Generated via drf-spectacular with comprehensive:

  • Request/response schemas
  • Authentication security schemes
  • Error response examples
  • Endpoint tags and descriptions

Target Audience: API clients, code generators, testing tools

Format: YAML (OpenAPI 3.0)

Accessing API Documentation​

The API includes live, interactive documentation powered by Swagger UI and ReDoc:

Swagger UI​

URL: http://localhost:8000/api/docs/ (Development) URL: https://api.coditect.com/api/docs/ (Production)

Features:

  • Interactive API explorer
  • Try-it-out functionality with live requests
  • Authentication testing with JWT bearer tokens
  • Request/response examples for all endpoints
  • Automatic request validation

Best For:

  • Testing API endpoints during development
  • Learning the API interactively
  • Debugging integration issues

ReDoc​

URL: http://localhost:8000/api/redoc/ (Development) URL: https://api.coditect.com/api/redoc/ (Production)

Features:

  • Clean, readable documentation layout
  • Three-panel design (navigation, content, examples)
  • Automatic code samples in multiple languages
  • Downloadable OpenAPI schema
  • Search functionality

Best For:

  • Reference documentation
  • API overview and exploration
  • Sharing with stakeholders

OpenAPI Schema Download​

URL: http://localhost:8000/api/schema/ (Development) URL: https://api.coditect.com/api/schema/ (Production)

Format: JSON

Download the raw OpenAPI schema for:

  • Code generation (client SDKs, server stubs)
  • API testing tools (Postman, Insomnia)
  • Documentation generators
  • Contract testing

Generating OpenAPI Schema​

Automatic Generation​

The OpenAPI schema is automatically available at runtime via the /api/schema/ endpoint.

Manual Generation​

To generate a static openapi-schema.yaml file:

# From project root
./scripts/generate-openapi-schema.sh

This script:

  1. Activates the virtual environment
  2. Runs database migrations if needed
  3. Generates openapi-schema.yaml using drf-spectacular
  4. Validates the schema

Requirements:

  • Virtual environment (venv/) must exist
  • Dependencies installed (pip install -r requirements.txt)
  • Django settings configured

Output: openapi-schema.yaml in project root

Manual Command (Alternative)​

# Activate virtual environment
source venv/bin/activate

# Set Django settings
export DJANGO_SETTINGS_MODULE=license_platform.settings.development

# Generate schema
python manage.py spectacular \
    --file openapi-schema.yaml \
    --format openapi \
    --validate

Using the Documentation​

For API Consumers​

  1. Start Here: Read api-documentation.md

    • Understand authentication (Firebase JWT)
    • Review session lifecycle (acquire → heartbeat → release)
    • Study error handling

  2. Interactive Testing: Use Swagger UI

  3. Integration: Use client examples

    • Python example in api-documentation.md
    • JavaScript example in api-documentation.md
    • Or generate client SDK from OpenAPI schema

For API Developers​

  1. Adding New Endpoints:

    from drf_spectacular.utils import extend_schema, OpenApiExample

    @extend_schema(
        tags=['Your Feature'],
        summary='Endpoint summary',
        description='Detailed description...',
        request=YourRequestSerializer,
        responses={
            200: OpenApiResponse(
                response=YourResponseSerializer,
                description='Success response',
                examples=[
                    OpenApiExample(
                        'Example Name',
                        value={...},
                        response_only=True,
                        status_codes=['200']
                    )
                ]
            ),
            400: OpenApiResponse(description='Validation error'),
        },
        auth=['JWTAuthentication']
    )
    class YourView(APIView):
        ...

  2. Updating Serializers:

    from drf_spectacular.utils import extend_schema_field
    from drf_spectacular.types import OpenApiTypes

    class YourSerializer(serializers.ModelSerializer):
        """
        Serializer description.

        Example:
            {
                "field1": "value1",
                "field2": 123
            }
        """

        computed_field = serializers.SerializerMethodField()

        @extend_schema_field(OpenApiTypes.INT)
        def get_computed_field(self, obj):
            return obj.compute_value()

  3. Regenerating Documentation:

    After making changes:

    ./scripts/generate-openapi-schema.sh

    Then verify at:

For QA/Testing​

  1. Import into Postman:

  2. Import into Insomnia:

  3. Automated Testing:

    # Install testing tools
    pip install schemathesis

    # Run automated API tests
    schemathesis run http://localhost:8000/api/schema/ \
        --checks all \
        --header "Authorization: Bearer YOUR_JWT_TOKEN"

Documentation Standards​

Endpoint Documentation Requirements​

All API endpoints MUST include:

✅ @extend_schema decorator with:

  • tags: Category grouping
  • summary: Brief one-line description
  • description: Detailed explanation with markdown
  • request: Request serializer (if applicable)
  • responses: All possible HTTP status codes with examples
  • auth: Authentication requirement

✅ Request examples for all inputs

✅ Response examples for:

  • Success responses (200, 201, etc.)
  • Common errors (400, 401, 404, 409, etc.)
  • Edge cases (410, 503, etc.)

✅ Error documentation with:

  • Status code
  • Error message format
  • When this error occurs

Serializer Documentation Requirements​

All serializers MUST include:

✅ Docstring with:

  • Purpose description
  • Example JSON in docstring

✅ Field descriptions via help_text

✅ @extend_schema_field for computed fields

Example Quality Standards​

Examples MUST:

  • Use realistic data (no "foo", "bar", "test123")
  • Include all required fields
  • Show actual UUID format
  • Include ISO 8601 timestamps
  • Demonstrate field validation

Validation and Quality Checks​

Schema Validation​

The spectacular command includes automatic validation:

python manage.py spectacular --validate

Checks:

  • OpenAPI 3.0 compliance
  • Schema completeness
  • Reference integrity
  • Type consistency

Documentation Linting​

Check documentation quality:

# Install spectral (OpenAPI linter)
npm install -g @stoplight/spectral-cli

# Lint schema
spectral lint openapi-schema.yaml

Coverage Check​

Ensure all endpoints are documented:

python manage.py spectacular --file - --format openapi | \
    python -c "import sys, json; \
    schema = json.load(sys.stdin); \
    print(f'Endpoints: {len(schema[\"paths\"])}'); \
    print(f'Schemas: {len(schema[\"components\"][\"schemas\"])}')"

Troubleshooting​

Schema Generation Fails​

Problem: ModuleNotFoundError when running spectacular

Solution:

  1. Ensure virtual environment is activated: source venv/bin/activate
  2. Install dependencies: pip install -r requirements.txt
  3. Install drf-spectacular: pip install drf-spectacular

Missing Examples in Swagger UI​

Problem: Endpoints show no examples

Solution:

  1. Check @extend_schema decorator includes examples=[...]
  2. Verify OpenApiExample has response_only=True
  3. Ensure status_codes matches response status

Authentication Not Working in Swagger UI​

Problem: 401 Unauthorized when testing

Solution:

  1. Click "Authorize" button in Swagger UI
  2. Enter token in format: Bearer YOUR_JWT_TOKEN (include "Bearer ")
  3. Or just: YOUR_JWT_TOKEN (Swagger adds "Bearer " automatically)
  4. Verify token is not expired (15 minute lifetime)

ReDoc Shows Outdated Documentation​

Problem: Changes not reflected in ReDoc

Solution:

  1. Clear browser cache (Cmd+Shift+R on Mac)
  2. Restart Django server: python manage.py runserver
  3. Regenerate schema: ./scripts/generate-openapi-schema.sh

Best Practices​

For API Documentation​

  1. Keep Examples Realistic: Use production-like data
  2. Document All Error Cases: Don't just show happy path
  3. Include Rate Limits: Document per-endpoint limits
  4. Show Complete Workflows: Demonstrate multi-step processes
  5. Update on Changes: Regenerate schema after any API changes

For API Consumers​

  1. Use Interactive Docs First: Test in Swagger UI before coding
  2. Handle All Error Cases: Don't assume success
  3. Implement Retries: Network failures happen
  4. Respect Rate Limits: Implement backoff strategies
  5. Monitor Token Expiry: Refresh tokens before expiration

For API Maintainers​

  1. Review Schema on PR: Ensure documentation matches code
  2. Test Examples: Verify all examples are valid
  3. Version API Changes: Use semantic versioning
  4. Announce Breaking Changes: Give consumers notice
  5. Monitor Usage: Track which endpoints are most used

Additional Resources​

Last Updated: November 30, 2025 Maintained By: CODITECT Backend Team Contact: api-support@coditect.com