Налаштування операції шляху¶
🌐 Переклад ШІ та людьми
Цей переклад виконано ШІ під керівництвом людей. 🤝
Можливі помилки через неправильне розуміння початкового змісту або неприродні формулювання тощо. 🤖
Ви можете покращити цей переклад, допомігши нам краще спрямовувати AI LLM.
Є кілька параметрів, які ви можете передати вашому «декоратору операції шляху» для налаштування.
Попередження
Зверніть увагу, що ці параметри передаються безпосередньо «декоратору операції шляху», а не вашій «функції операції шляху».
Код статусу відповіді¶
Ви можете визначити (HTTP) status_code, який буде використано у відповіді вашої «операції шляху».
Можна передати безпосередньо цілий код, наприклад 404.
Якщо ви не пам'ятаєте призначення числових кодів, скористайтеся скороченими константами в status:
from fastapi import FastAPI, status
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(item: Item) -> Item:
return item
Цей код статусу буде використано у відповіді та додано до схеми OpenAPI.
Технічні деталі
Ви також можете використати from starlette import status.
FastAPI надає той самий starlette.status як fastapi.status для вашої зручності як розробника. Але він походить безпосередньо зі Starlette.
Мітки¶
Ви можете додати мітки до вашої «операції шляху», передайте параметр tags зі list із str (зазвичай лише один str):
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", tags=["items"])
async def create_item(item: Item) -> Item:
return item
@app.get("/items/", tags=["items"])
async def read_items():
return [{"name": "Foo", "price": 42}]
@app.get("/users/", tags=["users"])
async def read_users():
return [{"username": "johndoe"}]
Вони будуть додані до схеми OpenAPI та використані інтерфейсами автоматичної документації:
Мітки з переліками¶
У великому застосунку ви можете накопичити багато міток і захочете переконатися, що завжди використовуєте ту саму мітку для пов'язаних «операцій шляху».
У таких випадках має сенс зберігати мітки в Enum.
FastAPI підтримує це так само, як і зі звичайними строками:
from enum import Enum
from fastapi import FastAPI
app = FastAPI()
class Tags(Enum):
items = "items"
users = "users"
@app.get("/items/", tags=[Tags.items])
async def get_items():
return ["Portal gun", "Plumbus"]
@app.get("/users/", tags=[Tags.users])
async def read_users():
return ["Rick", "Morty"]
Короткий опис і опис¶
Ви можете додати summary і description:
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post(
"/items/",
summary="Create an item",
description="Create an item with all the information, name, description, price, tax and a set of unique tags",
)
async def create_item(item: Item) -> Item:
return item
Опис зі строки документації¶
Оскільки описи зазвичай довгі та займають кілька рядків, ви можете оголосити опис «операції шляху» у строці документації функції, і FastAPI прочитає його звідти.
Ви можете писати Markdown у строці документації, його буде інтерпретовано та показано коректно (з урахуванням відступів у строці документації).
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", summary="Create an item")
async def create_item(item: Item) -> Item:
"""
Create an item with all the information:
- **name**: each item must have a name
- **description**: a long description
- **price**: required
- **tax**: if the item doesn't have tax, you can omit this
- **tags**: a set of unique tag strings for this item
"""
return item
Його буде використано в інтерактивній документації:
Опис відповіді¶
Ви можете вказати опис відповіді параметром response_description:
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post(
"/items/",
summary="Create an item",
response_description="The created item",
)
async def create_item(item: Item) -> Item:
"""
Create an item with all the information:
- **name**: each item must have a name
- **description**: a long description
- **price**: required
- **tax**: if the item doesn't have tax, you can omit this
- **tags**: a set of unique tag strings for this item
"""
return item
Інформація
Зверніть увагу, що response_description стосується саме відповіді, а description стосується «операції шляху» загалом.
Перевірте
OpenAPI визначає, що кожна «операція шляху» потребує опису відповіді.
Тому, якщо ви його не надасте, FastAPI автоматично згенерує «Successful response».
Позначити операцію шляху як застарілу¶
Якщо потрібно позначити «операцію шляху» як застарілу, але не видаляючи її, передайте параметр deprecated:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", tags=["items"])
async def read_items():
return [{"name": "Foo", "price": 42}]
@app.get("/users/", tags=["users"])
async def read_users():
return [{"username": "johndoe"}]
@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
return [{"item_id": "Foo"}]
У інтерактивній документації вона буде чітко позначена як застаріла:
Подивіться, як виглядають застарілі та незастарілі «операції шляху»:
Підсумок¶
Ви можете легко налаштовувати та додавати метадані до ваших «операцій шляху», передаючи параметри «декораторам операцій шляху».