Автоматическая генерация OpenAPI спецификаций в Python

Расширенные примеры работы с OpenAPI в Python

Кастомизация метаданных и группировка эндпоинтов в FastAPI

from fastapi import FastAPI, APIRouter
from pydantic import BaseModel

app = FastAPI(
    title="Сложное API",
    version="2.0.0",
    description="API с дополнительными метаданными",
    openapi_tags=[
        {"name": "users", "description": "Операции с пользователями"},
        {"name": "items", "description": "Управление товарами"},
    ]
)

router_items = APIRouter(tags=["items"])

class ItemCreate(BaseModel):
    name: str
    price: float

@router_items.post("/items", response_model=ItemCreate, summary="Создать товар")
def create_item(item: ItemCreate):
    return item

app.include_router(router_items)

# Добавление произвольного поля в OpenAPI
app.openapi_extra = {
    "x-logo": {
        "url": "https://example.com/logo.png"
    }
}

Результат: в /openapi.json появится секция x-logo, а теги объединят эндпоинты. Swagger UI отобразит группы.

Добавление схемы безопасности (Bearer Token) в FastAPI

from fastapi.security import HTTPBearer
from fastapi import FastAPI, Depends

app = FastAPI()
security = HTTPBearer()

@app.get("/secure", dependencies=[Depends(security)])
def secure_endpoint():
    return {"message": "Доступ разрешён"}

# Автоматически в OpenAPI добавится компонент securitySchemes с bearerAuth

// Фрагмент openapi.json
"components": {
  "securitySchemes": {
    "HTTPBearer": {
      "type": "http",
      "scheme": "bearer"
    }
  }
},
"security": [{"HTTPBearer": []}]

Генерация клиентского кода с помощью openapi-generator

После получения openapi.json можно сгенерировать клиент на любом языке.

# Установка генератора
npm install @openapitools/openapi-generator-cli -g

# Генерация Python клиента
openapi-generator-cli generate -i openapi.json -g python -o ./python-client

# Генерация TypeScript клиента
openapi-generator-cli generate -i openapi.json -g typescript-axios -o ./ts-client

В полученном клиенте все эндпоинты и модели уже типизированы. Это ускоряет разработку и снижает количество ошибок.

Тестирование API с использованием OpenAPI схемы

Можно проверять ответы на соответствие схеме с помощью библиотеки jsonschema.

import json
import requests
from jsonschema import validate, ValidationError

# Загрузка схемы
with open("openapi.json") as f:
    spec = json.load(f)

# Получение схемы для ответа 200 для метода GET /items
schema = spec["paths"]["/items"]["get"]["responses"]["200"]["content"]["application/json"]["schema"]

# Запрос к API
response = requests.get("http://localhost:8000/items")
try:
    validate(instance=response.json(), schema=schema)
    print("Ответ соответствует OpenAPI схеме")
except ValidationError as e:
    print(f"Ошибка валидации: {e.message}")

Генерация OpenAPI схемы из существующих данных (на примере Flask + apispec)

from flask import Flask, jsonify
from apispec import APISpec
from apispec.ext.flask import FlaskPlugin
from apispec_webframeworks.flask import FlaskPlugin as FlaskPlugin2  # альтернатива

app = Flask(__name__)

@app.route("/api/data")
def get_data():
    return jsonify([{"id": 1, "value": "test"}])

spec = APISpec(title="Dynamic API", version="1.0.0", openapi_version="3.0.2", plugins=[FlaskPlugin2()])
with app.test_request_context():
    spec.path(view=get_data)

import json
print(json.dumps(spec.to_dict(), indent=2))

Результат: будет сгенерирован путь /api/data с ответом 200, но без указания модели (так как нет схемы). Для полноты нужно добавить схему Marshmallow.

Работа с несколькими версиями API

FastAPI позволяет иметь несколько приложений с разными префиксами.

from fastapi import FastAPI

app_v1 = FastAPI(title="API v1", version="1.0.0")
app_v2 = FastAPI(title="API v2", version="2.0.0")

@app_v1.get("/status")
def status_v1():
    return {"version": "v1"}

@app_v2.get("/status")
def status_v2():
    return {"version": "v2"}

# Монтируем с разными префиксами
from fastapi import APIRouter
router = APIRouter()
router.mount("/v1", app_v1)
router.mount("/v2", app_v2)

# Итоговое приложение
app = FastAPI()
app.include_router(router)

# Документация каждой версии доступна по /v1/docs и /v2/docs