FAPI001 `endpoint-metadata`¶

Co robi¶

Zgłasza operację ścieżki FastAPI (@router.get(...), @app.post(...), @router.api_route(...)), której wpis OpenAPI nie ma metadanych wymaganych przez projekt. Jedna diagnostyka na endpoint, na jego dekoratorze, wymienia wszystko, czego brakuje. Domyślnie reguła wymaga:

podsumowania: summary= albo opisu, czyli description= lub docstringu (FastAPI czyta docstring, gdy nie ma description=, a podsumowanie wraca wtedy do nazwy funkcji);
modelu odpowiedzi: response_model= albo adnotacji typu zwracanego, z której FastAPI zbuduje schemat, czym nie są Response i jego podklasy. Trasa ze status_code=204 jest zwolniona;
jawnego status_code= dla POST i DELETE, bo 200 rzadko pasuje do tworzenia albo usuwania;
pola description w każdym wpisie responses=.

Można też wymagać tagów i operation_id (zobacz Konfigurację). Trasy z include_in_schema=False, w dekoratorze albo w ich APIRouter(...), nie mają wpisu OpenAPI i są pomijane.

Dlaczego to źle¶

Schemat OpenAPI to kontrakt, z którego powstają frontend i każdy wygenerowany klient, a FastAPI wypełnia go tylko tym, co kod deklaruje. Endpoint bez podsumowania pokazuje nazwę funkcji, bez modelu odpowiedzi pusty schemat, a tworzenie zasobu, które odpowiada 200, nic klientowi nie mówi. Agenci dodają endpointy szybko i rzadko wracają po metadane.

Przykład¶

Z trzema warstwami z INW001 włącz FAPI001:

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"]

Agent dodaje endpoint, który tworzy zamówienie:

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/

Poprawiony: endpoint mówi, co robi, co zwraca i jakim statusem odpowiada.

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

Jak naprawić¶

Dodaj do dekoratora to, co wymienia diagnostyka: summary="..." albo docstring, status_code=, "description" w każdym wpisie responses=.
Zadeklaruj model, który endpoint zwraca, jako adnotację typu zwracanego albo response_model=. Bezpośrednio zwracany Response nie daje FastAPI niczego do udokumentowania.
Jeśli projekt nie chce któregoś sprawdzenia, wyłącz je w [tool.inwards.rules.endpoint-metadata] zamiast dopisywać zastępcze metadane.

Bezpieczeństwo poprawki¶

Bez automatycznej poprawki (autofix: false). Podsumowanie i kod statusu to decyzje o API, a nie tekst do wygenerowania.

Konfiguracja¶

Opt-in: reguła zgłasza tylko wtedy, gdy extend-select albo select wymienia FAPI001. Jej opcje z wartościami domyślnymi: