FAPI001 `endpoint-metadata`¶

What it does¶

Reports a FastAPI path operation (@router.get(...), @app.post(...), @router.api_route(...)) whose OpenAPI entry lacks metadata the project requires. One finding per endpoint, on its decorator, lists everything missing. By default it requires:

a summary: summary=, or a description, description= or a docstring (FastAPI reads the docstring when description= is absent, and the summary then falls back to the function name);
a response model: response_model=, or a return annotation FastAPI can build a schema from, which Response and its subclasses aren't. A status_code=204 route is exempt;
an explicit status_code= on POST and DELETE, since 200 is rarely right for a create or a delete;
a description in every entry of responses=.

Tags and operation_id can be required too (see Configuration). Routes with include_in_schema=False, on the decorator or on their APIRouter(...), have no OpenAPI entry and are skipped.

Why is this bad¶

The OpenAPI schema is the contract a frontend and every generated client are built from, and FastAPI fills it only from what the code declares. An endpoint without a summary shows its function name, one without a response model shows an empty schema, and a create that answers 200 tells the client nothing happened. Agents add endpoints fast and rarely come back for the metadata.

Example¶

With the three layers from INW001, turn FAPI001 on:

pyproject.toml

[tool.inwards]
layers = [
  { name = "domain", modules = ["shop.domain"] },
  { name = "application", modules = ["shop.application"] },
  { name = "infrastructure", modules = ["shop.infrastructure"] },
]

[tool.inwards.rules]
extend-select = ["FAPI001"]

An agent adds an endpoint that creates an order:

shop/infrastructure/orders.py

from fastapi import APIRouter

router = APIRouter(prefix="/orders", tags=["orders"])


@router.post("/")
async def create_order(body: OrderIn):
    ...

inwards check

shop/infrastructure/orders.py:6:1: FAPI001 `create_order` (POST /) has no summary, explicit status code or response model in its OpenAPI metadata.
  fix: Declare the missing OpenAPI metadata on `@router.post("/")`.
    1. Add `summary="..."` (or a docstring) and `status_code=201` to `@router.post("/")`, and a return annotation or `response_model=...`.
    2. Write a summary that says what the endpoint does, not the function name; declare the model the endpoint really returns.
    3. If the project doesn't want this metadata, ask the user to change [tool.inwards.rules.endpoint-metadata]; don't edit [tool.inwards] yourself.
  docs: https://sircypkowskyy.github.io/inwards/rules/FAPI001/

Fixed: the endpoint says what it does, what it returns and which status it answers with.

shop/infrastructure/orders.py

from fastapi import APIRouter
from pydantic import BaseModel

router = APIRouter(prefix="/orders", tags=["orders"])


class OrderIn(BaseModel):
    product_id: int


class OrderOut(BaseModel):
    id: int


@router.post("/", status_code=201, summary="Place an order")
async def create_order(body: OrderIn) -> OrderOut:
    return OrderOut(id=1)

inwards check

How to fix¶

Add what the finding lists to the decorator: summary="..." or a docstring, status_code=, "description" in each responses= entry.
Declare the model the endpoint returns, as a return annotation or response_model=. Returning a Response directly gives FastAPI nothing to document.
If the project doesn't want a check, turn it off in [tool.inwards.rules.endpoint-metadata] rather than adding placeholder metadata.

Fix safety¶

No automatic fix (autofix: false). A summary and a status code are decisions about the API, not text to generate.

Configuration¶

Opt-in: it reports only when extend-select or select lists FAPI001. Its options, with their defaults: