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

Да ты посмотри, какая тема подъехала — про эту вашу документацию для API! Ну, блядь, OpenAPI, он же бывший Swagger, сука. Это типа такой стандарт, чтобы твоё API, как последнюю мартышку, не пришлось на пальцах объяснять каждому новому чуваку.

Представь: сидит кодер, пьёт кофе, и ему надо твой сервис использовать. А ты ему — «ну там, POST-запрос сделай, JSON-ку какую-то передай, поля вот такие». Он тебе в ответ: «Да иди ты нахуй, я твои поля сам выдумаю». А вот если у тебя OpenAPI прописан — всё, пиздец, вопросов нет. Автоматом и документация-красавица вылезает, и код клиента сгенерить можно, и серверную заглушку на коленке собрать. Красота, ёпта!

В Питоне, понятное дело, для этого свои приблуды есть. Смотри, как это бывает:

1. FastAPI — тут вообще сказка, блядь! Ты просто пишешь код, а он, сука, сам всё понимает! Аннотации типов, модели Pydantic — и вуаля, документация уже готова. Открываешь в браузере /docs — и тебе целый интерактивный цирк с конями, где можно API тыкать и смотреть, что отвалится. Серьёзно, проще некуда.

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, и прямо в докстрингах к функциям пишешь описание в этом ёбаном YAML. Выглядит, конечно, как заклинание древнее, но работает.

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-spectacular ставит. Эта штука, блядь, как сыщик — сама ползает по твоим Serializer'ам, ViewSet'ам и роутам, и из всего этого бардака строит красивую схему. Ничего руками прописывать не надо, она всё вынюхает.

А главный плюс всего этого цирка в чём? Да в том, что документация всегда, блядь, актуальная! Не получится так, что ты API поменял, а документация осталась где-то в прошлой жизни. Всё генерится прямо из кода — значит, если код работает, то и описание ему соответствует. Идеально, ёбана!