OpenAPI docs and schema are out of date

[mihow]

Issue Summary

The OpenAPI schema at http://localhost:8000/api/v2/schema/ is outdated and does not accurately reflect our current API implementation. Multiple endpoints, custom actions, and serializer schemas have not been registered or are incorrect.

Background

We use Django REST Framework (DRF) with drf-spectacular for automatic OpenAPI documentation generation. While spectacular can auto-detect most schemas and standard CRUD operations, it cannot automatically detect all our custom actions and complex serializer relationships.

Analysis of the current API implementation:

• 15+ missing endpoints (custom actions, status endpoints)
• Serializer schemas have incorrect field definitions and missing fields
• Authentication requirements are not properly documented

When the OpenAPI schema is accurate, it can be used to automatically generate TypeScript types, a client/package for R studio and python, and an MCP server for AI tools to communicate with.

Problem Categories

Category 1: Missing Custom Action Endpoints

Issue: 13 custom actions are implemented but not documented in the OpenAPI schema.

Examples:

Deployment Sync Action

• Endpoint: POST /api/v2/deployments/{id}/sync/
• Implementation: DeploymentViewSet.sync() method
• Purpose: Queue background job to sync deployment data

OpenAPI Addition:

/api/v2/deployments/{id}/sync/:
  post:
    operationId: deployments_sync_create
    description: Queue a task to sync data from the deployment's data source.
    parameters:
    - in: path
      name: id
      schema:
        type: integer
      description: A unique integer value identifying this deployment.
      required: true
    tags:
    - deployments
    security:
    - tokenAuth: []
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              properties:
                job_id:
                  type: integer
                project_id:
                  type: integer
        description: Job queued successfully

Event Timeline Action

• Endpoint: GET /api/v2/events/{id}/timeline/
• Implementation: EventViewSet.timeline() method
• Purpose: Return detection timeline data

OpenAPI Addition:

/api/v2/events/{id}/timeline/:
  get:
    operationId: events_timeline_retrieve
    description: Return a list of time intervals and the number of detections for each interval, including intervals where no source images were captured, along with meta information.
    parameters:
    - in: path
      name: id
      schema:
        type: integer
      description: A unique integer value identifying this event.
      required: true
    - in: query
      name: resolution_minutes
      schema:
        type: integer
        minimum: 1
        default: 1
      description: Number of minutes per timeline interval
      required: false
    tags:
    - events
    security:
    - tokenAuth: []
    responses:
      '200':
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventTimelineSerializer'
        description: Timeline data retrieved successfully

---

Category 3: Missing Status Endpoints

Issue: Two status endpoints from urlpatterns are not in the schema.

Summary Status Endpoint

• Endpoint: GET /api/v2/status/summary/
• Implementation: SummaryView class
• Purpose: Return model counts with visibility filters

OpenAPI Addition:

/api/v2/status/summary/:
  get:
    operationId: status_summary_retrieve
    description: Return counts of all models, applying visibility filters for draft projects.
    parameters:
    - in: query
      name: project_id
      schema:
        type: integer
      description: Filter by project ID
      required: false
    tags:
    - status
    security:
    - tokenAuth: []
    responses:
      '200':
        content:
          application/json:
            schema:
              type: object
              properties:
                projects_count:
                  type: integer
                deployments_count:
                  type: integer
                events_count:
                  type: integer
                captures_count:
                  type: integer
                occurrences_count:
                  type: integer
                taxa_count:
                  type: integer
                num_sessions:
                  type: integer
                num_species:
                  type: integer
                last_updated:
                  type: string
                  format: date-time
        description: Model counts retrieved successfully

---

Category 4: Incorrect Serializer Schemas

Issue: Many serializer schemas have missing fields, wrong types, or incorrect requirements.

Example: Project Serializer Updates

Current Schema Issues:

• Missing settings, feature_flags, deployments fields
• draft field not marked as nullable
• Missing owner information

Required Schema Updates:

Project:
  type: object
  properties:
    id:
      type: integer
      readOnly: true
    name:
      type: string
      maxLength: 80
    description:
      type: string
    details:
      type: string
      format: uri
      readOnly: true
    deployments_count:
      type: integer
      readOnly: true
    created_at:
      type: string
      format: date-time
      readOnly: true
    updated_at:
      type: string
      format: date-time
      readOnly: true
    image:
      type: string
      format: uri
      nullable: true
    draft:
      type: boolean
      description: Indicates whether this project is in draft mode
      nullable: true  # Add this
    deployments:  # Add this
      type: array
      items:
        $ref: '#/components/schemas/DeploymentNestedSerializerWithLocationAndCounts'
      readOnly: true
    summary_data:  # Add this
      type: string
      readOnly: true
    owner:  # Add this
      allOf:
      - $ref: '#/components/schemas/UserNested'
      readOnly: true
    feature_flags:  # Add this
      type: object
      additionalProperties: {}
      readOnly: true
    settings:  # Add this
      allOf:
      - $ref: '#/components/schemas/ProjectSettings'
      readOnly: true
  required:
  - created_at
  - deployments
  - deployments_count
  - details
  - feature_flags
  - id
  - name
  - owner
  - summary_data
  - updated_at

Example: SourceImage Serializer Navigation Fields

Missing Fields: Event navigation fields for image browsing

SourceImage:
  # ... existing fields ...
  properties:
    # ... existing properties ...
    event_next_capture_id:  # Add this
      type: integer
      nullable: true
      description: Return the next capture in the event.
      readOnly: true
    event_prev_capture_id:  # Add this
      type: integer
      nullable: true
      description: Return the previous capture in the event.
      readOnly: true
    event_current_capture_index:  # Add this
      type: integer
      nullable: true
      description: Return the index of the current capture in the event.
      readOnly: true
    event_total_captures:  # Add this
      type: integer
      nullable: true
      description: Return the total number of captures in the event.
      readOnly: true

---

Category 5: Authentication Documentation Issues

Issue: Some endpoints allow unauthenticated access but aren't properly documented.

Example: Taxon suggest endpoint allows anonymous access

/api/v2/taxa/suggest/:
  get:
    # ... other properties ...
    security:
    - tokenAuth: []
    - {}  # Allow anonymous access

---

Implementation Priority

2. High Priority: Add missing custom actions (Deployment.sync, Event.timeline, etc.)
3. Medium Priority: Add status endpoints
4. Medium Priority: Update serializer schemas with correct fields
5. Low Priority: Fix authentication documentation

2. Enhance drf-spectacular Configuration

Leverage drf-spectacular's capabilities to better detect our custom actions and complex serializers. This may involve:

• Adding @extend_schema decorators to custom actions in ami/main/api/views.py
• Configuring serializer relationships in ami/main/api/serializers.py
• Setting up proper authentication documentation

3. Manual Schema Extensions (if needed)

For complex cases that spectacular cannot auto-detect, provide targeted schema extensions to ensure complete and accurate API documentation.

Relevant Files

File	GitHub Link	Purpose
config/api_router.py	View	Router configuration with duplicate registrations
ami/main/api/views.py	View	ViewSets with custom actions and serializer logic
ami/main/api/serializers.py	View	Serializer definitions with field mappings
ami/jobs/views.py	View	Job-related custom actions (cancel, retry, run)
ami/exports/views.py	View	Export functionality endpoints
ami/ml/views.py	View	ML pipeline and algorithm endpoints
config/settings/base.py	View	DRF and spectacular configuration

Success Metrics

• Router configuration is clean with no duplicate registrations
• All custom actions are properly documented with comprehensive parameters and responses
• Status endpoints provide clear documentation for monitoring capabilities
• Serializer schemas accurately represent our robust data models (fields, types, requirements)
• Authentication requirements are clearly documented for secure API usage
• Schema successfully validates against OpenAPI 3.0.3 specification
• All endpoints demonstrate proper response schemas that match actual API behavior

Verification Steps

• API documentation at http://localhost:8000/api/v2/schema/ showcases our full API capabilities
• OpenAPI validation tools confirm schema compliance and completeness
• API consumers can effectively use our documentation for seamless integration
• Development team has accurate reference for API behavior and testing
• Custom actions are discoverable and well-documented for advanced use cases