Path Operation Yapılandırması¶

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

Onu yapılandırmak için path operation decorator’ınıza geçebileceğiniz çeşitli parametreler vardır.

Uyarı

Bu parametrelerin path operation function’ınıza değil, doğrudan path operation decorator’ına verildiğine dikkat edin.

Response Status Code¶

Path operation’ınızın response’unda kullanılacak (HTTP) status_code’u tanımlayabilirsiniz.

404 gibi int kodu doğrudan verebilirsiniz.

Ancak her sayısal kodun ne işe yaradığını hatırlamıyorsanız, status içindeki kısayol sabitlerini kullanabilirsiniz:

Python 3.10+

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()


@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(item: Item) -> Item:
    return item

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()


@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(item: Item) -> Item:
    return item

Bu status code response’da kullanılacak ve OpenAPI şemasına eklenecektir.

Teknik Detaylar

from starlette import status da kullanabilirsiniz.

FastAPI, geliştirici olarak işinizi kolaylaştırmak için starlette.status’u fastapi.status olarak da sunar. Ancak kaynağı doğrudan Starlette’tir.

Tags¶

Path operation’ınıza tag ekleyebilirsiniz; tags parametresine str öğelerinden oluşan bir list verin (genellikle tek bir str):

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()


@app.post("/items/", tags=["items"])
async def create_item(item: Item) -> Item:
    return item


@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()


@app.post("/items/", tags=["items"])
async def create_item(item: Item) -> Item:
    return item


@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]

Bunlar OpenAPI şemasına eklenecek ve otomatik dokümantasyon arayüzleri tarafından kullanılacaktır:

Enum ile Tags¶

Büyük bir uygulamanız varsa, zamanla birden fazla tag birikebilir ve ilişkili path operation’lar için her zaman aynı tag’i kullandığınızdan emin olmak isteyebilirsiniz.

Bu durumlarda tag’leri bir Enum içinde tutmak mantıklı olabilir.

FastAPI bunu düz string’lerde olduğu gibi aynı şekilde destekler:

Python 3.9+

from enum import Enum

from fastapi import FastAPI

app = FastAPI()


class Tags(Enum):
    items = "items"
    users = "users"


@app.get("/items/", tags=[Tags.items])
async def get_items():
    return ["Portal gun", "Plumbus"]


@app.get("/users/", tags=[Tags.users])
async def read_users():
    return ["Rick", "Morty"]

Özet ve açıklama¶

Bir summary ve description ekleyebilirsiniz:

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()


@app.post(
    "/items/",
    summary="Create an item",
    description="Create an item with all the information, name, description, price, tax and a set of unique tags",
)
async def create_item(item: Item) -> Item:
    return item

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()


@app.post(
    "/items/",
    summary="Create an item",
    description="Create an item with all the information, name, description, price, tax and a set of unique tags",
)
async def create_item(item: Item) -> Item:
    return item

Docstring’den Description¶

Açıklamalar genelde uzun olur ve birden fazla satıra yayılır; bu yüzden path operation açıklamasını, fonksiyonun içinde docstring olarak tanımlayabilirsiniz; FastAPI de onu buradan okur.

Docstring içinde Markdown yazabilirsiniz; doğru şekilde yorumlanır ve gösterilir (docstring girintisi dikkate alınarak).

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()


@app.post("/items/", summary="Create an item")
async def create_item(item: Item) -> Item:
    """
    Create an item with all the information:

    - **name**: each item must have a name
    - **description**: a long description
    - **price**: required
    - **tax**: if the item doesn't have tax, you can omit this
    - **tags**: a set of unique tag strings for this item
    """
    return item

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()


@app.post("/items/", summary="Create an item")
async def create_item(item: Item) -> Item:
    """
    Create an item with all the information:

    - **name**: each item must have a name
    - **description**: a long description
    - **price**: required
    - **tax**: if the item doesn't have tax, you can omit this
    - **tags**: a set of unique tag strings for this item
    """
    return item

Interactive docs’ta şöyle kullanılacaktır:

Response description¶

response_description parametresi ile response açıklamasını belirtebilirsiniz:

Python 3.10+

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()


@app.post(
    "/items/",
    summary="Create an item",
    response_description="The created item",
)
async def create_item(item: Item) -> Item:
    """
    Create an item with all the information:

    - **name**: each item must have a name
    - **description**: a long description
    - **price**: required
    - **tax**: if the item doesn't have tax, you can omit this
    - **tags**: a set of unique tag strings for this item
    """
    return item

🤓 Other versions and variants

Python 3.9+

from typing import Union

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Union[str, None] = None
    price: float
    tax: Union[float, None] = None
    tags: set[str] = set()


@app.post(
    "/items/",
    summary="Create an item",
    response_description="The created item",
)
async def create_item(item: Item) -> Item:
    """
    Create an item with all the information:

    - **name**: each item must have a name
    - **description**: a long description
    - **price**: required
    - **tax**: if the item doesn't have tax, you can omit this
    - **tags**: a set of unique tag strings for this item
    """
    return item

Bilgi

response_description özellikle response’u ifade eder; description ise genel olarak path operation’ı ifade eder.

Ek bilgi

OpenAPI, her path operation için bir response description zorunlu kılar.

Bu yüzden siz sağlamazsanız, FastAPI otomatik olarak "Successful response" üretir.

Bir path operation’ı Deprecate Etmek¶

Bir path operation’ı kaldırmadan, deprecated olarak işaretlemeniz gerekiyorsa deprecated parametresini verin:

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/", tags=["items"])
async def read_items():
    return [{"name": "Foo", "price": 42}]


@app.get("/users/", tags=["users"])
async def read_users():
    return [{"username": "johndoe"}]


@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
    return [{"item_id": "Foo"}]

Interactive docs’ta deprecated olduğu net şekilde işaretlenecektir:

Deprecated olan ve olmayan path operation’ların nasıl göründüğüne bakın:

Özet¶

Path operation’larınızı, path operation decorator’larına parametre geçirerek kolayca yapılandırabilir ve metadata ekleyebilirsiniz.