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

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

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

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

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

title str Назва API.

summary str Короткий опис API. Доступно з OpenAPI 3.1.0, ReadyAPI 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`	Email контактної особи або організації. Повинен бути у форматі електронної пошти.

license_info

dict

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

license_info поля

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

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

Python 3.8+

from readyapi import ReadyAPI

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 = ReadyAPI(
    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 та ReadyAPI 0.99.0 Ви також можете налаштувати license_info за допомогою identifier замість url.

Наприклад:

Python 3.8+

from readyapi import ReadyAPI

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 = ReadyAPI(
    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.8+

from readyapi import ReadyAPI

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://readyapi.github.io/",
        },
    },
]

app = ReadyAPI(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 зі своїми операціями шляху (і APIRouter) для призначення їх до різних тегів:

Python 3.8+

from readyapi import ReadyAPI

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://readyapi.github.io/",
        },
    },
]

app = ReadyAPI(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.8+

from readyapi import ReadyAPI

app = ReadyAPI(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.8+

from readyapi import ReadyAPI

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


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