Metadata ve Doküman URL'leri¶

🌐 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.

English version

FastAPI uygulamanızda çeşitli metadata yapılandırmalarını özelleştirebilirsiniz.

API için Metadata¶

OpenAPI spesifikasyonunda ve otomatik API doküman arayüzlerinde kullanılan şu alanları ayarlayabilirsiniz:

Parametre Tip Açıklama

title str API'nin başlığı.

summary str API'nin kısa özeti. OpenAPI 3.1.0, FastAPI 0.99.0 sürümünden itibaren mevcut.

description str API'nin kısa açıklaması. Markdown kullanabilir.

version string API'nin sürümü. Bu, OpenAPI'nin değil, kendi uygulamanızın sürümüdür. Örneğin 2.5.0.

terms_of_service str API'nin Kullanım Koşulları (Terms of Service) için bir URL. Verilirse, URL formatında olmalıdır.

contact

dict

Yayınlanan API için iletişim bilgileri. Birden fazla alan içerebilir.

contact alanları

Parametre	Tip	Açıklama
`name`	`str`	İletişim kişisi/kuruluşunu tanımlayan ad.
`url`	`str`	İletişim bilgilerine işaret eden URL. URL formatında OLMALIDIR.
`email`	`str`	İletişim kişisi/kuruluşunun e-posta adresi. E-posta adresi formatında OLMALIDIR.

license_info

dict

Yayınlanan API için lisans bilgileri. Birden fazla alan içerebilir.

license_info alanları

Parametre	Tip	Açıklama
`name`	`str`	ZORUNLU (`license_info` ayarlanmışsa). API için kullanılan lisans adı.
`identifier`	`str`	API için bir SPDX lisans ifadesi. `identifier` alanı, `url` alanıyla karşılıklı olarak dışlayıcıdır (ikisi aynı anda kullanılamaz). OpenAPI 3.1.0, FastAPI 0.99.0 sürümünden itibaren mevcut.
`url`	`str`	API için kullanılan lisansa ait URL. URL formatında OLMALIDIR.

Şu şekilde ayarlayabilirsiniz:

Python 3.9+

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
)


@app.get("/items/")
async def read_items():
    return [{"name": "Katana"}]

İpucu

description alanına Markdown yazabilirsiniz; çıktı tarafında render edilir.

Bu yapılandırmayla otomatik API dokümanları şöyle görünür:

License identifier¶

OpenAPI 3.1.0 ve FastAPI 0.99.0 sürümünden itibaren, license_info içinde url yerine bir identifier da ayarlayabilirsiniz.

Örneğin:

Python 3.9+

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "identifier": "Apache-2.0",
    },
)


@app.get("/items/")
async def read_items():
    return [{"name": "Katana"}]

Tag'ler için Metadata¶

openapi_tags parametresiyle, path operation'larınızı gruplamak için kullandığınız farklı tag'ler adına ek metadata da ekleyebilirsiniz.

Bu parametre, her tag için bir sözlük (dictionary) içeren bir liste alır.

Her sözlük şunları içerebilir:

name (zorunlu): path operation'larda ve APIRouter'larda tags parametresinde kullandığınız tag adıyla aynı olan bir str.
description: tag için kısa bir açıklama içeren str. Markdown içerebilir ve doküman arayüzünde gösterilir.
externalDocs: harici dokümanları tanımlayan bir dict:
- description: harici dokümanlar için kısa açıklama içeren str.
- url (zorunlu): harici dokümantasyonun URL'sini içeren str.

Tag'ler için metadata oluşturun¶

users ve items tag'lerini içeren bir örnekle deneyelim.

Tag'leriniz için metadata oluşturup openapi_tags parametresine geçin:

Python 3.9+

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

Açıklamaların içinde Markdown kullanabileceğinizi unutmayın; örneğin "login" kalın (login) ve "fancy" italik (fancy) olarak gösterilecektir.

İpucu

Kullandığınız tüm tag'ler için metadata eklemek zorunda değilsiniz.

Tag'lerinizi kullanın¶

path operation'larınızı (ve APIRouter'ları) farklı tag'lere atamak için tags parametresini kullanın:

Python 3.9+

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

Bilgi

Tag'ler hakkında daha fazlası için: Path Operation Configuration.

Dokümanları kontrol edin¶

Artık dokümanlara baktığınızda, eklediğiniz tüm metadata gösterilir:

Tag sırası¶

Her tag metadata sözlüğünün listedeki sırası, doküman arayüzünde gösterilecek sırayı da belirler.

Örneğin alfabetik sıralamada users, items'tan sonra gelirdi; ancak listedeki ilk sözlük olarak users metadata'sını eklediğimiz için, dokümanlarda önce o görünür.

OpenAPI URL'si¶

Varsayılan olarak OpenAPI şeması /openapi.json adresinden sunulur.

Ancak bunu openapi_url parametresiyle yapılandırabilirsiniz.

Örneğin /api/v1/openapi.json adresinden sunulacak şekilde ayarlamak için:

Python 3.9+

from fastapi import FastAPI

app = FastAPI(openapi_url="/api/v1/openapi.json")


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

OpenAPI şemasını tamamen kapatmak isterseniz openapi_url=None ayarlayabilirsiniz; bu, onu kullanan dokümantasyon arayüzlerini de devre dışı bırakır.

Doküman URL'leri¶

Dahil gelen iki dokümantasyon arayüzünü yapılandırabilirsiniz:

Swagger UI: /docs adresinden sunulur.
- URL'sini docs_url parametresiyle ayarlayabilirsiniz.
- docs_url=None ayarlayarak devre dışı bırakabilirsiniz.
ReDoc: /redoc adresinden sunulur.
- URL'sini redoc_url parametresiyle ayarlayabilirsiniz.
- redoc_url=None ayarlayarak devre dışı bırakabilirsiniz.

Örneğin Swagger UI'yi /documentation adresinden sunup ReDoc'u kapatmak için:

Python 3.9+

from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url=None)


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