OpenAPI'yi Genişletme¶

🌐 Yapay Zekâ ve İnsanlar Tarafından Çeviri

Bu çeviri, insanlar tarafından yönlendirilen bir yapay zekâ ile oluşturuldu. 🤝

Orijinal anlamın yanlış anlaşılması ya da kulağa doğal gelmeme gibi hatalar içerebilir. 🤖

Yapay zekâyı daha iyi yönlendirmemize yardımcı olarak bu çeviriyi iyileştirebilirsiniz.

İngilizce sürüm

Oluşturulan OpenAPI şemasını değiştirmeniz gereken bazı durumlar olabilir.

Bu bölümde bunun nasıl yapılacağını göreceksiniz.

Normal süreç¶

Normal (varsayılan) süreç şöyledir.

Bir FastAPI uygulamasının (instance) OpenAPI şemasını döndürmesi beklenen bir .openapi() metodu vardır.

Uygulama nesnesi oluşturulurken, /openapi.json (ya da openapi_url için ne ayarladıysanız o) için bir path operation kaydedilir.

Bu path operation, uygulamanın .openapi() metodunun sonucunu içeren bir JSON response döndürür.

Varsayılan olarak .openapi() metodunun yaptığı şey, .openapi_schema özelliğinde içerik olup olmadığını kontrol etmek ve varsa onu döndürmektir.

Eğer yoksa, fastapi.openapi.utils.get_openapi konumundaki yardımcı (utility) fonksiyonu kullanarak şemayı üretir.

Ve get_openapi() fonksiyonu şu parametreleri alır:

title: Dokümanlarda gösterilen OpenAPI başlığı.
version: API'nizin sürümü, örn. 2.5.0.
openapi_version: Kullanılan OpenAPI specification sürümü. Varsayılan olarak en günceli: 3.1.0.
summary: API'nin kısa özeti.
description: API'nizin açıklaması; markdown içerebilir ve dokümanlarda gösterilir.
routes: route'ların listesi; bunların her biri kayıtlı path operations'lardır. app.routes içinden alınırlar.

Bilgi

summary parametresi OpenAPI 3.1.0 ve üzeri sürümlerde vardır; FastAPI 0.99.0 ve üzeri tarafından desteklenmektedir.

Varsayılanları ezme¶

Yukarıdaki bilgileri kullanarak aynı yardımcı fonksiyonla OpenAPI şemasını üretebilir ve ihtiyacınız olan her parçayı override edebilirsiniz.

Örneğin, özel bir logo eklemek için ReDoc'un OpenAPI extension'ını ekleyelim.

Normal FastAPI¶

Önce, tüm FastAPI uygulamanızı her zamanki gibi yazın:

Python 3.9+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


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


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

OpenAPI şemasını üretme¶

Ardından, bir custom_openapi() fonksiyonunun içinde aynı yardımcı fonksiyonu kullanarak OpenAPI şemasını üretin:

Python 3.9+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


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


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

OpenAPI şemasını değiştirme¶

Artık OpenAPI şemasındaki info "object"'ine özel bir x-logo ekleyerek ReDoc extension'ını ekleyebilirsiniz:

Python 3.9+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


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


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

OpenAPI şemasını cache'leme¶

Ürettiğiniz şemayı saklamak için .openapi_schema özelliğini bir "cache" gibi kullanabilirsiniz.

Böylece bir kullanıcı API docs'larınızı her açtığında uygulamanız şemayı tekrar tekrar üretmek zorunda kalmaz.

Şema yalnızca bir kez üretilecektir; sonraki request'ler için de aynı cache'lenmiş şema kullanılacaktır.

Python 3.9+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


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


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

Metodu override etme¶

Şimdi .openapi() metodunu yeni fonksiyonunuzla değiştirebilirsiniz.

Python 3.9+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


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


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

Kontrol edin¶

http://127.0.0.1:8000/redoc adresine gittiğinizde, özel logonuzu kullandığınızı göreceksiniz (bu örnekte FastAPI'nin logosu):