Розширення OpenAPI¶

🌐 Переклад ШІ та людьми

Цей переклад виконано ШІ під керівництвом людей. 🤝

Можливі помилки через неправильне розуміння початкового змісту або неприродні формулювання тощо. 🤖

Ви можете покращити цей переклад, допомігши нам краще спрямовувати AI LLM.

Англійська версія

У деяких випадках вам може знадобитися змінити згенеровану схему OpenAPI.

У цьому розділі ви побачите як це зробити.

Звичайний процес¶

Звичайний (типовий) процес такий.

Застосунок FastAPI (екземпляр) має метод .openapi(), який має повертати схему OpenAPI.

Під час створення об'єкта застосунку реєструється операція шляху для /openapi.json (або для того значення, яке ви встановили в openapi_url).

Вона просто повертає відповідь JSON з результатом методу .openapi() застосунку.

Типово метод .openapi() перевіряє властивість .openapi_schema, і якщо там вже є дані, повертає їх.

Якщо ні, він генерує їх за допомогою утилітарної функції fastapi.openapi.utils.get_openapi.

Функція get_openapi() приймає такі параметри:

title: Заголовок OpenAPI, показується в документації.
version: Версія вашого API, напр. 2.5.0.
openapi_version: Версія специфікації OpenAPI, що використовується. Типово остання: 3.1.0.
summary: Короткий підсумок API.
description: Опис вашого API; може містити markdown і буде показаний у документації.
routes: Список маршрутів, це кожна з зареєстрованих операцій шляху. Їх беруть з app.routes.

Інформація

Параметр summary доступний в OpenAPI 3.1.0 і вище, підтримується FastAPI 0.99.0 і вище.

Переписування типових значень¶

Використовуючи наведене вище, ви можете скористатися тією ж утилітарною функцією для генерації схеми OpenAPI і переписати потрібні частини.

Наприклад, додаймо розширення OpenAPI для ReDoc для додавання власного логотипа.

Звичайний FastAPI¶

Спочатку напишіть ваш застосунок FastAPI як зазвичай:

Python 3.10+

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¶

Далі використайте ту ж утилітарну функцію для генерації схеми OpenAPI всередині функції custom_openapi():

Python 3.10+

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¶

Тепер можна додати розширення ReDoc, додавши власний x-logo до «об'єкта» info у схемі OpenAPI:

Python 3.10+

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¶

Ви можете використовувати властивість .openapi_schema як «кеш» для збереження згенерованої схеми.

Так вашому застосунку не доведеться щоразу генерувати схему, коли користувач відкриває документацію вашого API.

Вона буде згенерована лише один раз, а потім та сама закешована схема використовуватиметься для наступних запитів.

Python 3.10+

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() вашою новою функцією.

Python 3.10+

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

Перевірте¶

Коли ви перейдете за адресою http://127.0.0.1:8000/redoc, побачите, що використовується ваш власний логотип (у цьому прикладі логотип FastAPI):