fastapi/docs/tr/docs/tutorial/metadata.md

Metadata ve Doküman URL'leri

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:

{* ../../docs_src/metadata/tutorial001_py310.py hl[3:16, 19:32] *}

/// tip | İpucu

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

///

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

Lisans Tanımlayıcısı

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:

{* ../../docs_src/metadata/tutorial001_1_py310.py hl[31] *}

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:

{* ../../docs_src/metadata/tutorial004_py310.py hl[3:16,18] *}

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

/// tip | İ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:

{* ../../docs_src/metadata/tutorial004_py310.py hl[21,26] *}

/// info | 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:

{* ../../docs_src/metadata/tutorial002_py310.py hl[3] *}

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:

{* ../../docs_src/metadata/tutorial003_py310.py hl[3] *}