Уяви, що ти створив повноцінний API з купою функцій, але без документації. Іншим розробникам користуватися таким API буде схоже на роботу з незнайомим інструментом без інструкції — доведеться методом спроб і помилок з'ясовувати, які команди доступні і як їх правильно викликати.
Саме тому документація API така важлива. Вона пояснює, як взаємодіяти з твоїм сервісом: які запити можна відправляти, які дані потрібні і які відповіді очікувати.
OpenAPI — це стандарт документування REST API, який FastAPI підтримує "з коробки". Завдяки цьому документація автоматично генерується для кожного ендпоінту. Це дає тобі:
- Наглядове представлення всіх доступних ендпоінтів API
- Чіткий опис потрібних параметрів і форматів даних
- Інформацію про можливі відповіді і коди стану
- Інтерактивний інтерфейс для тестування запитів прямо в браузері
І що особливо цінно — все це відбувається автоматично, без потреби писати додатковий код!
Знайомство з OpenAPI і Swagger UI
FastAPI інтегрується з OpenAPI і надає два зручні інтерфейси для документування і тестування твого API:
- Swagger UI — це красива панель в веб-інтерфейсі, де ти можеш бачити свої ендпоінти, відправляти запити і одразу перевіряти їх відповіді.
- ReDoc — альтернативний інтерфейс документації з більш стриманим дизайном. Підійде тим, хто любить мінімалізм.
Swagger UI доступний за замовчуванням за адресою /docs, а ReDoc — на /redoc.
Практичне застосування документації
Час переходити від слів до діла. Давай додамо кілька ендпоінтів у наш додаток і подивимось, як автоматично генерується документація.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/")
async def read_items(q: str = None):
"""
Повертає список предметів.
Якщо вказано параметр `q`, повертає елементи, що містять `q`.
"""
if q:
return {"items": [f"Item {i}" for i in range(1, 6) if q in f"Item {i}"]}
return {"items": [f"Item {i}" for i in range(1, 6)]}
Крок 1: Запусти додаток через Uvicorn:
uvicorn main:app --reload
Крок 2: Відкрий браузер і перейди за адресою http://127.0.0.1:8000/docs.
Бум! Перед тобою інтерфейс Swagger UI. Тут ти побачиш ендпоінт /items/ і його опис. Ти можеш клікнути на ендпоінт, вказати параметри і відправити запит прямо звідси.
Налаштування документації для ендпоінтів
FastAPI дозволяє додавати опис, summary і багато іншого для кожного ендпоінту. Наприклад, ти можеш використовувати description і summary, щоб краще описати маршрут.
@app.get(
"/users/",
summary="Отримати список користувачів",
description="Цей ендпоінт повертає список усіх зареєстрованих користувачів. "
"Можна використовувати параметр `q` для фільтрації."
)
async def get_users(q: str = None):
return {"users": ["Alice", "Bob", "Carol"]}
Тепер заголовок і опис маршруту відображаються в Swagger UI. Це робить документацію зручною для читання і розуміння.
Додавання прикладів запитів і відповідей
Якщо ти хочеш показати, як працюють твої ендпоінти, можеш додати приклади запитів і відповідей.
from fastapi.responses import JSONResponse
@app.get(
"/products/",
summary="Список продуктів",
responses={
200: {
"description": "Успішне отримання списку продуктів",
"content": {
"application/json": {
"example": {
"products": ["Product 1", "Product 2"]
}
}
}
}
}
)
async def get_products():
return JSONResponse(content={"products": ["Product A", "Product B"]})
Тепер у Swagger UI ти побачиш приклад, який краще пояснить іншим розробникам, чого очікувати від API.
Захист документації через конфігурацію
А що, якщо ми не хочемо показувати документацію всім підряд? FastAPI дозволяє обмежити доступ до документації. Наприклад, ти можеш вимкнути Swagger UI:
app = FastAPI(docs_url=None, redoc_url=None)
Тепер документація недоступна. Проте ти можеш створити прихований ендпоінт для своїх розробників:
from fastapi.openapi.utils import get_openapi
@app.get("/custom_docs")
async def custom_docs():
return get_openapi(
title="My API",
version="1.0.0",
description="Це мій кастомний API",
routes=app.routes
)
Як тестувати API через Swagger UI
Swagger UI — не просто красива документація. Це ще й потужний інструмент розробки! Ти можеш:
- Відправляти запити з параметрами і отримувати дані.
- Тестувати різні сценарії роботи твого API.
- Вивчати можливі HTTP-коди відповідей.
Прямо в інтерфейсі ти можеш перейти до будь‑якого ендпоінту, натиснути кнопку "Try it out" і протестувати запити.
«Вау, а що ще круто?»
FastAPI настільки розумний, що автоматично конвертує Pydantic-моделі в схеми OpenAPI. Якщо ти визначиш Pydantic-модель для валідації даних, вона одразу з'явиться в документації.
Приклад:
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
is_offer: bool = None
@app.post("/items/", response_model=Item)
async def create_item(item: Item):
"""
Створює новий предмет.
"""
return item
Swagger UI покаже деталі моделі Item і обов'язкові поля. Це допоможе іншим розробникам зрозуміти, які дані потрібно відправляти.
Що робити, якщо виникли помилки?
У процесі роботи з документацією можуть виникати помилки. Наприклад:
- Ти забув опис параметра, і Swagger UI виглядає "порожньо".
- Ти вказав неправильні типи даних, і генерація схеми OpenAPI не працює.
У такому випадку завжди корисно прочитати офіційну документацію FastAPI. А ще, пам'ятай — якщо в коді помилка, Swagger UI про це скаже!
Тепер у твоєму арсеналі є не тільки вміння створювати API, а й робити їх зрозумілими для інших — за допомогою OpenAPI і Swagger UI.
Повір, на співбесіді вміння показати документацію API одразу додасть тобі +100 очок! 🚀
ПЕРЕЙДІТЬ В ПОВНУ ВЕРСІЮ