Path Operation İleri Düzey Yapılandırma¶
🌐 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.
OpenAPI operationId¶
Uyarı
OpenAPI konusunda "uzman" değilseniz, muhtemelen buna ihtiyacınız yok.
path operation’ınızda kullanılacak OpenAPI operationId değerini operation_id parametresiyle ayarlayabilirsiniz.
Bunun her operation için benzersiz olduğundan emin olmanız gerekir.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", operation_id="some_specific_id_you_define")
async def read_items():
return [{"item_id": "Foo"}]
operationId olarak path operation function adını kullanma¶
API’lerinizin function adlarını operationId olarak kullanmak istiyorsanız, hepsini dolaşıp her path operation’ın operation_id değerini APIRoute.name ile override edebilirsiniz.
Bunu, tüm path operation’ları ekledikten sonra yapmalısınız.
from fastapi import FastAPI
from fastapi.routing import APIRoute
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"item_id": "Foo"}]
def use_route_names_as_operation_ids(app: FastAPI) -> None:
"""
Simplify operation IDs so that generated API clients have simpler function
names.
Should be called only after all routes have been added.
"""
for route in app.routes:
if isinstance(route, APIRoute):
route.operation_id = route.name # in this case, 'read_items'
use_route_names_as_operation_ids(app)
İpucu
app.openapi() fonksiyonunu manuel olarak çağırıyorsanız, bunu yapmadan önce operationId’leri güncellemelisiniz.
Uyarı
Bunu yaparsanız, her bir path operation function’ın adının benzersiz olduğundan emin olmanız gerekir.
Farklı modüllerde (Python dosyalarında) olsalar bile.
OpenAPI’den Hariç Tutma¶
Bir path operation’ı üretilen OpenAPI şemasından (dolayısıyla otomatik dokümantasyon sistemlerinden) hariç tutmak için include_in_schema parametresini kullanın ve False yapın:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", include_in_schema=False)
async def read_items():
return [{"item_id": "Foo"}]
Docstring’den İleri Düzey Açıklama¶
OpenAPI için, bir path operation function’ın docstring’inden kullanılacak satırları sınırlandırabilirsiniz.
Bir \f (escape edilmiş "form feed" karakteri) eklerseniz, FastAPI OpenAPI için kullanılan çıktıyı bu noktada keser.
Dokümantasyonda görünmez, ancak diğer araçlar (Sphinx gibi) geri kalan kısmı kullanabilir.
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
\f
:param item: User input.
"""
return item
🤓 Other versions and variants
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
\f
:param item: User input.
"""
return item
Ek Responses¶
Muhtemelen bir path operation için response_model ve status_code tanımlamayı görmüşsünüzdür.
Bu, bir path operation’ın ana response’u ile ilgili metadata’yı tanımlar.
Ek response’ları; modelleri, status code’ları vb. ile birlikte ayrıca da tanımlayabilirsiniz.
Dokümantasyonda bununla ilgili ayrı bir bölüm var; OpenAPI’de Ek Responses sayfasından okuyabilirsiniz.
OpenAPI Extra¶
Uygulamanızda bir path operation tanımladığınızda, FastAPI OpenAPI şemasına dahil edilmek üzere o path operation ile ilgili metadata’yı otomatik olarak üretir.
Teknik Detaylar
OpenAPI spesifikasyonunda buna Operation Object denir.
Bu, path operation hakkında tüm bilgileri içerir ve otomatik dokümantasyonu üretmek için kullanılır.
tags, parameters, requestBody, responses vb. alanları içerir.
Bu path operation’a özel OpenAPI şeması normalde FastAPI tarafından otomatik üretilir; ancak siz bunu genişletebilirsiniz.
İpucu
Bu, düşük seviyeli bir genişletme noktasıdır.
Yalnızca ek response’lar tanımlamanız gerekiyorsa, bunu yapmanın daha pratik yolu OpenAPI’de Ek Responses kullanmaktır.
Bir path operation için OpenAPI şemasını openapi_extra parametresiyle genişletebilirsiniz.
OpenAPI Extensions¶
Örneğin bu openapi_extra, OpenAPI Extensions tanımlamak için faydalı olabilir:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", openapi_extra={"x-aperture-labs-portal": "blue"})
async def read_items():
return [{"item_id": "portal-gun"}]
Otomatik API dokümanlarını açtığınızda, extension’ınız ilgili path operation’ın en altında görünür.
Ayrıca ortaya çıkan OpenAPI’yi (API’nizde /openapi.json) görüntülerseniz, extension’ınızı ilgili path operation’ın bir parçası olarak orada da görürsünüz:
{
"openapi": "3.1.0",
"info": {
"title": "FastAPI",
"version": "0.1.0"
},
"paths": {
"/items/": {
"get": {
"summary": "Read Items",
"operationId": "read_items_items__get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
},
"x-aperture-labs-portal": "blue"
}
}
}
}
Özel OpenAPI path operation şeması¶
openapi_extra içindeki dictionary, path operation için otomatik üretilen OpenAPI şemasıyla derinlemesine (deep) birleştirilir.
Böylece otomatik üretilen şemaya ek veri ekleyebilirsiniz.
Örneğin, Pydantic ile FastAPI’nin otomatik özelliklerini kullanmadan request’i kendi kodunuzla okuyup doğrulamaya karar verebilirsiniz; ancak yine de OpenAPI şemasında request’i tanımlamak isteyebilirsiniz.
Bunu openapi_extra ile yapabilirsiniz:
from fastapi import FastAPI, Request
app = FastAPI()
def magic_data_reader(raw_body: bytes):
return {
"size": len(raw_body),
"content": {
"name": "Maaaagic",
"price": 42,
"description": "Just kiddin', no magic here. ✨",
},
}
@app.post(
"/items/",
openapi_extra={
"requestBody": {
"content": {
"application/json": {
"schema": {
"required": ["name", "price"],
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"},
"description": {"type": "string"},
},
}
}
},
"required": True,
},
},
)
async def create_item(request: Request):
raw_body = await request.body()
data = magic_data_reader(raw_body)
return data
Bu örnekte herhangi bir Pydantic model tanımlamadık. Hatta request body JSON olarak parsed bile edilmiyor; doğrudan bytes olarak okunuyor ve magic_data_reader() fonksiyonu bunu bir şekilde parse etmekten sorumlu oluyor.
Buna rağmen, request body için beklenen şemayı tanımlayabiliriz.
Özel OpenAPI content type¶
Aynı yöntemi kullanarak, Pydantic model ile JSON Schema’yı tanımlayıp bunu path operation için özel OpenAPI şeması bölümüne dahil edebilirsiniz.
Ve bunu, request içindeki veri tipi JSON olmasa bile yapabilirsiniz.
Örneğin bu uygulamada, FastAPI’nin Pydantic modellerinden JSON Schema çıkarmaya yönelik entegre işlevselliğini ve JSON için otomatik doğrulamayı kullanmıyoruz. Hatta request content type’ını JSON değil, YAML olarak tanımlıyoruz:
import yaml
from fastapi import FastAPI, HTTPException, Request
from pydantic import BaseModel, ValidationError
app = FastAPI()
class Item(BaseModel):
name: str
tags: list[str]
@app.post(
"/items/",
openapi_extra={
"requestBody": {
"content": {"application/x-yaml": {"schema": Item.model_json_schema()}},
"required": True,
},
},
)
async def create_item(request: Request):
raw_body = await request.body()
try:
data = yaml.safe_load(raw_body)
except yaml.YAMLError:
raise HTTPException(status_code=422, detail="Invalid YAML")
try:
item = Item.model_validate(data)
except ValidationError as e:
raise HTTPException(status_code=422, detail=e.errors(include_url=False))
return item
Buna rağmen, varsayılan entegre işlevselliği kullanmasak da, YAML olarak almak istediğimiz veri için JSON Schema’yı manuel üretmek üzere bir Pydantic model kullanmaya devam ediyoruz.
Ardından request’i doğrudan kullanıp body’yi bytes olarak çıkarıyoruz. Bu da FastAPI’nin request payload’ını JSON olarak parse etmeye çalışmayacağı anlamına gelir.
Sonrasında kodumuzda bu YAML içeriğini doğrudan parse ediyor, ardından YAML içeriğini doğrulamak için yine aynı Pydantic modeli kullanıyoruz:
import yaml
from fastapi import FastAPI, HTTPException, Request
from pydantic import BaseModel, ValidationError
app = FastAPI()
class Item(BaseModel):
name: str
tags: list[str]
@app.post(
"/items/",
openapi_extra={
"requestBody": {
"content": {"application/x-yaml": {"schema": Item.model_json_schema()}},
"required": True,
},
},
)
async def create_item(request: Request):
raw_body = await request.body()
try:
data = yaml.safe_load(raw_body)
except yaml.YAMLError:
raise HTTPException(status_code=422, detail="Invalid YAML")
try:
item = Item.model_validate(data)
except ValidationError as e:
raise HTTPException(status_code=422, detail=e.errors(include_url=False))
return item
İpucu
Burada aynı Pydantic modeli tekrar kullanıyoruz.
Aynı şekilde, başka bir yöntemle de doğrulama yapabilirdik.