Skip to content

OpenAPI Schema Generation

This guide explains how to generate the OpenAPI schema for the Tracker API, addressing the circular reference issues that can occur.

🔄 Complete Workflow Overview

This document covers Step 1 of the complete OpenAPI update workflow:

  1. Generate Updated OpenAPI Schema ← You are here
  2. Update Frontend Types & Tests → See OpenAPI-MSW Integration Guide

For the complete frontend testing integration workflow, see the OpenAPI-MSW Integration Guide.

Quick Reference

# Most common workflow - generate schema from running dev container
./scripts/generate_simplified_openapi.py --output openapi.json

# Alternative - export from running API
./scripts/export_openapi.py --container tracker-restapi-dev-1 --output openapi.json

# Validate the generated schema
python -c "import json; json.load(open('openapi.json')); print('✅ Valid JSON')"

Problem

The default OpenAPI schema generation in FastAPI can encounter issues with circular references in Pydantic models, resulting in a "maximum recursion depth exceeded" error. This prevents the generation of a valid OpenAPI schema.

Solution

We've created two approaches to solve this issue:

1. Temporary Modification Approach

The fix_openapi_recursion.py script temporarily modifies the FastAPI application to handle circular references by:

  1. Backing up the main.py file
  2. Modifying the custom_openapi function to set a lower recursion limit
  3. Restarting the container
  4. Generating the OpenAPI schema
  5. Restoring the original main.py file
  6. Restarting the container again

Usage:

./scripts/fix_openapi_recursion.py --container <container-name>

The generate_simplified_openapi.py script generates a simplified OpenAPI schema by directly inspecting the API routes without relying on FastAPI's schema generation. This approach:

  1. Extracts API routes from the FastAPI application
  2. Generates a simplified OpenAPI schema based on the routes
  3. Adds basic schema definitions for common response models
  4. Saves the schema to a file

Usage:

./scripts/generate_simplified_openapi.py [--output openapi.json] [--title "API Title"] [--version "1.0.0"]

Generated Schema

The generated OpenAPI schema includes:

  • API paths with operations, parameters, and responses
  • Schema components for request and response models
  • Security schemes for authentication
  • Basic error responses

This schema can be used for documentation, client generation, and other purposes without the circular reference issues.

Export Script

The export_openapi.py script can be used to fetch the OpenAPI schema from a running FastAPI application. It supports both local and Docker container environments.

Usage:

./scripts/export_openapi.py [--api-url URL] [--output FILE] [--container NAME] [--internal-port PORT] [--verbose]

Recommendations

For regular development, use the generate_simplified_openapi.py script to generate the OpenAPI schema. This approach is more reliable and doesn't require modifying the application code.

For production, consider implementing a more robust solution that handles circular references in the FastAPI application itself, such as using custom schema generators or modifying the Pydantic models to avoid circular references.

Next Steps: Frontend Integration

After generating the OpenAPI schema, you'll typically want to update your frontend types and tests:

  1. Update TypeScript Types: Generate TypeScript definitions from the new schema
  2. Update MSW Mocks: Synchronize your Mock Service Worker handlers with the new API schema
  3. Update Vitest Tests: Ensure your frontend tests work with the updated schema

For detailed instructions on these steps, see the OpenAPI-MSW Integration Guide.

Development Workflow

For the typical development workflow when API changes are made:

# 1. Generate updated schema (after API changes)
./scripts/generate_simplified_openapi.py --output openapi.json

# 2. Continue with frontend integration (see MSW Integration Guide)
# - Update TypeScript types
# - Update MSW handlers
# - Run tests to validate