Skip to content
Sarj Standards

Python · correctness

fastapi-openapi-contract

python:fastapi-openapi-contract

FastAPI operations must publish explicit request, response, and OpenAPI contracts.

Code
SARJ094
Default
error
Fix
none
Languages
python

Why

Complete route metadata keeps generated OpenAPI accurate for clients, validation, and review.

Fix

Declare route metadata, typed parameters, response schemas, and documented alternate responses.

Before / after

Executed by this rule’s unit tests.

Before

Visible operation without required metadata

api.py · focus
from fastapi import APIRouter

router = APIRouter()

@router.get('/users')
async def users() -> list[UserResponse]:
    return []

After

Operation with an explicit OpenAPI contract

api.py · focus
from fastapi import APIRouter

router = APIRouter()

@router.get('/users', summary='Read users', description='Returns visible users.', status_code=200)
async def users() -> list[UserResponse]:
    return []

Limits

  • Hidden routes, WebSocket handlers, tests, generated files, and unrelated decorators are excluded.
  • Dynamic response mappings are accepted when their contents cannot be resolved statically.
  • Imported dependency aliases are followed only through unique, nonsymlinked relative or same-package modules inside the detected checkout; traversal is bounded and ambiguity remains diagnostic.