Метадані та URL-адреси документації¶

Ви можете налаштувати кілька конфігурацій метаданих у Вашому додатку FastAPI.

Метадані для API¶

Ви можете встановити такі поля, які використовуються в специфікації OpenAPI та в автоматично згенерованих інтерфейсах документації API:

Параметр Тип Опис

title str Назва API.

summary str Короткий підсумок API. Доступно з OpenAPI 3.1.0, FastAPI 0.99.0.

description str Короткий опис API. Може використовувати Markdown.

version string Версія API. Це версія Вашого додатка, а не OpenAPI. Наприклад, 2.5.0.

terms_of_service str URL до умов використання API. Якщо вказано, має бути у форматі URL.

contact

dict

Інформація для контакту з опублікованим API. Може містити кілька полів.

contact поля

Параметр	Тип	Опис
`name`	`str`	Ідентифікаційне ім'я контактної особи або організації.
`url`	`str`	URL, що вказує на контактну інформацію. МАЄ бути у форматі URL.
`email`	`str`	Адреса електронної пошти контактної особи або організації. МАЄ бути у форматі адреси електронної пошти.

license_info

dict

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

license_info поля

Параметр	Тип	Опис
`name`	`str`	ОБОВ'ЯЗКОВО (якщо встановлено `license_info`). Назва ліцензії для API.
`identifier`	`str`	Ліцензійний вираз за SPDX для API. Поле `identifier` взаємовиключне з полем `url`. Доступно з OpenAPI 3.1.0, FastAPI 0.99.0.
`url`	`str`	URL до ліцензії, яка використовується для API. МАЄ бути у форматі URL.

Ви можете налаштувати їх наступним чином:

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"}]

Порада

У полі description можна використовувати Markdown, і він буде відображатися у результаті.

З цією конфігурацією автоматична документація API виглядатиме так:

Ідентифікатор ліцензії¶

З початку використання OpenAPI 3.1.0 та FastAPI 0.99.0 Ви також можете налаштувати license_info за допомогою identifier замість url.

Наприклад:

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": "MIT",
    },
)


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

Метадані для тегів¶

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

Він приймає список, який містить один словник для кожного тега.

Кожен словник може містити:

name (обов'язково): str з тією ж назвою тегу, яку Ви використовуєте у параметрі tags у Ваших операціях шляху та APIRouters.
description: str з коротким описом тегу. Може містити Markdown і буде показано в інтерфейсі документації.
externalDocs: dict, який описує зовнішню документацію з такими полями:
- description: str з коротким описом зовнішньої документації.
- url (обов'язково): str з URL-адресою зовнішньої документації.

Створення метаданих для тегів¶

Спробуймо це на прикладі з тегами для users та items.

Створіть метадані для своїх тегів і передайте їх у параметр openapi_tags:

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"}]

Зверніть увагу, що в описах можна використовувати Markdown, наприклад, "login" буде показано жирним шрифтом (login), а "fancy" буде показано курсивом (fancy).

Порада

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

Використовуйте свої теги¶

Використовуйте параметр tags зі своїми операціями шляху (і APIRouters), щоб призначити їх до різних тегів:

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"}]

Інформація

Детальніше про теги читайте в розділі Конфігурація операції шляху.

Перевірте документацію¶

Тепер, якщо Ви перевірите документацію, вона покаже всі додаткові метадані:

Порядок тегів¶

Порядок кожного словника метаданих тегу також визначає порядок відображення в інтерфейсі документації.

Наприклад, хоча users мав би йти після items в алфавітному порядку, він відображається перед ними, оскільки ми додали їхні метадані як перший словник у списку.

URL для OpenAPI¶

За замовчуванням схема OpenAPI надається за адресою /openapi.json.

Але Ви можете налаштувати це за допомогою параметра openapi_url.

Наприклад, щоб налаштувати його на /api/v1/openapi.json:

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, Ви можете встановити openapi_url=None, це також вимкне інтерфейси документації, які її використовують.

URL-адреси документації¶

Ви можете налаштувати два інтерфейси користувача для документації, які включені:

Swagger UI: доступний за адресою /docs.
- Ви можете змінити його URL за допомогою параметра docs_url.
- Ви можете вимкнути його, встановивши docs_url=None.
ReDoc: доступний за адресою /redoc.
- Ви можете змінити його URL за допомогою параметра redoc_url.
- Ви можете вимкнути його, встановивши redoc_url=None.

Наприклад, щоб налаштувати Swagger UI на /documentation і вимкнути ReDoc:

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"}]