Как создать документацию OpenAPI (Swagger) для API на Python?

OpenAPI (ранее Swagger) — это стандарт для описания RESTful API. Он позволяет автоматически генерировать интерактивную документацию, клиентские SDK и серверные заглушки.

В Python документация обычно создается с помощью специализированных библиотек, которые интегрируются с веб-фреймворками.

Способы генерации:

1. FastAPI (встроенная поддержка) FastAPI автоматически генерирует OpenAPI-схему на основе моделей Pydantic и аннотаций типов. Документация доступна по умолчанию по путям /docs (Swagger UI) и /redoc (ReDoc).

   from fastapi import FastAPI
   from pydantic import BaseModel
   
   app = FastAPI()
   
   class Item(BaseModel):
       name: str
       price: float
   
   @app.post("/items/")
   async def create_item(item: Item):
       return item

   Это самый простой и современный способ.

2. Flask (с помощью flasgger) Библиотека flasgger позволяет описывать эндпоинты в YAML-формате прямо в docstrings функций.

   from flask import Flask
   from flasgger import Swagger
   
   app = Flask(__name__)
   swagger = Swagger(app)
   
   @app.route('/api/users/<int:user_id>')
   def get_user(user_id):
       """
       Получение пользователя по ID
       ---
       parameters:
         - name: user_id
           in: path
           type: integer
           required: true
       responses:
         200:
           description: Данные пользователя
       """
       return {'id': user_id, 'name': 'John Doe'}

3. Django REST Framework (DRF) Используются сторонние пакеты, такие как drf-spectacular (рекомендуется) или drf-yasg. Они анализируют Serializers, ViewSets и настройки маршрутизации для построения схемы.

Основное преимущество такого подхода — документация всегда синхронизирована с кодом, так как генерируется из него напрямую.