</>
halfcoder

Гайды

Документация API: Swagger, ReDoc и OpenAPI в FastAPI

Метаданные приложения, теги и summary, Field examples, responses, скрытие docs в проде, кастомный OpenAPI.

~10 мин чтения

BackendPythonFastAPIДокументация APISwagger

Документация API: Swagger, ReDoc и OpenAPI в FastAPI

FastAPI генерирует OpenAPI 3 схему из типов аннотаций и Field. Swagger UI и ReDoc подключаются из коробки. Этот гайд — как сделать документацию читаемой и точной. База — Быстрый старт с FastAPI.

1. Метаданные приложения

python
app = FastAPI(
    title="Orders API",
    description="Внутренний API заказов. Подробнее: [wiki](https://...)",
    version="1.2.0",
    terms_of_service="https://example.com/terms",
    contact={"name": "Platform", "email": "api@example.com"},
    license_info={"name": "Proprietary"},
    openapi_tags=[
        {"name": "orders", "description": "Создание и чтение заказов"},
        {"name": "admin", "description": "Только для роли admin"},
    ],
)

2. Теги и summary на эндпоинтах

python
@app.post(
    "/orders",
    response_model=OrderRead,
    status_code=201,
    tags=["orders"],
    summary="Создать заказ",
    response_description="Созданный заказ с id",
)
def create_order(payload: OrderCreate):
    ...

3. Field для JSON Schema

python
class OrderCreate(BaseModel):
    customer_id: int = Field(..., description="ID клиента в CRM", examples=[1001])
    lines: list[Line] = Field(..., min_length=1)

examples попадают в OpenAPI и подсказывают в Swagger.

4. Ответы и ошибки в схеме

python
@app.get(
    "/orders/{order_id}",
    responses={
        200: {"description": "OK"},
        404: {"description": "Заказ не найден", "model": ProblemDetail},
    },
)
def get_order(order_id: int):
    ...

Единый формат ошибок (RFC 7807 problem+json) улучшает DX.

5. Скрыть или переименовать доку в проде

python
app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

Или отдавать /docs только при DEBUG через условное создание приложения / reverse proxy ACL.

6. Кастомный OpenAPI

python
from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title=app.title,
        version=app.version,
        routes=app.routes,
        description=app.description,
    )
    schema["info"]["x-logo"] = {"url": "https://..."}
    app.openapi_schema = schema
    return app.openapi_schema

app.openapi = custom_openapi

Полезно для security schemes (OAuth2 flows), общих components.

В schema["servers"] можно перечислить url для dev/stage/prod — Swagger UI подставит выбранный base URL; удобно для QA без ручного редактирования хоста в «Try it out».

7. Swagger UI параметры

python
from fastapi.openapi.docs import get_swagger_ui_html

@app.get("/docs", include_in_schema=False)
async def swagger_ui():
    return get_swagger_ui_html(
        openapi_url="/openapi.json",
        title="API",
        swagger_js_url="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
        swagger_css_url="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
        swagger_ui_parameters={"persistAuthorization": True},
    )

persistAuthorization — удобно для JWT в браузере; см. JWT и OAuth2.

8. Генерация клиентов

Из openapi.json: OpenAPI Generator, orval (TypeScript), datamodel-codegen (Python models). В CI проверяйте, что схема не ломается без мажорного bump версии API. Спецификация OpenAPI: spec.openapis.org.

Снимок схемы в артефакте CI (curl "$BASE/openapi.json" -o openapi.json) позволяет диффать контракт между PR и ловить случайные переименования полей до деплоя.

Связанные материалы

Дальше: тег Swagger · тег FastAPI